CONTRIBUTING.md 4.9 KB
Newer Older
1 2
Contributing to Asuran
======================
Nathan McCarty's avatar
Nathan McCarty committed
3

4
We encourage anyone, regardless of skill level, to contribute. The worst that will happen is someone coming along to mentor you in the right direction.
Nathan McCarty's avatar
Nathan McCarty committed
5

6
We only ask that you please use gitlab for contributions. If you have some adversion to gitlab, or reason not to use it, please contact me on either the Matrix chat or via email and we can make arrangements.
Nathan McCarty's avatar
Nathan McCarty committed
7

8 9
Contributions
-------------
Nathan McCarty's avatar
Nathan McCarty committed
10 11 12

Contributions should be made in the form of gitlab issues or pull requests.

Nathan McCarty's avatar
Nathan McCarty committed
13
Contributors' names will be added to [`HALL_OF_FAME.md`](HALL_OF_FAME.md).
Nathan McCarty's avatar
Nathan McCarty committed
14 15 16 17 18

For those submitting bug reports, your name will be added once your bug report is confirmed.

For those making code contributions, your name will be added once you land your first PR.

19
If you don't want your name added, just say so and we wont.
Nathan McCarty's avatar
Nathan McCarty committed
20

21 22
Getting started
---------------
Nathan McCarty's avatar
Nathan McCarty committed
23

24
As a general workflow, once you find something you want to work on, fork the repository, do the work, then submit a PR for review.
Nathan McCarty's avatar
Nathan McCarty committed
25

26
Our issues have five tags relating the expected difficulty. The first three directly relate the expected difficulty and work load:
Nathan McCarty's avatar
Nathan McCarty committed
27

28
-	[`D-EASY`](https://gitlab.com/asuran-rs/asuran/issues?label_name%5B%5D=D-EASY)
Nathan McCarty's avatar
Nathan McCarty committed
29

30
These issues are expected to be easy to work on, requiring only basic understand of the project and rust in general, and not taking too much work to do.
Nathan McCarty's avatar
Nathan McCarty committed
31

32
-	[`D-MEDIUM`](https://gitlab.com/asuran-rs/asuran/issues?label_name%5B%5D=D-MEDIUM)
Nathan McCarty's avatar
Nathan McCarty committed
33

34 35 36 37 38
These issues are expected to take a not insubstantial amount of time to work, and more than a passing familiarity with the project.

-	[`D-HARD`](https://gitlab.com/asuran-rs/asuran/issues?label_name%5B%5D=D-HARD)

These issues are expected to take up large amounts of time or require in depth knowledge of the project and rust itself.
Nathan McCarty's avatar
Nathan McCarty committed
39

Nathan McCarty's avatar
Nathan McCarty committed
40
The next two describe other aspect of the work and are good labels for new contributors to go by:
Nathan McCarty's avatar
Nathan McCarty committed
41

42 43 44
-	[`Easy Tasks`](https://gitlab.com/asuran-rs/asuran/issues?label_name%5B%5D=Easy+Tasks)

These issues may have a difficulty rating of medium or hard, however, they have individual independent tasks on them that, if they were their own issue, would be categorized as easy.
Nathan McCarty's avatar
Nathan McCarty committed
45

46
-	[`Good First Issue`](https://gitlab.com/asuran-rs/asuran/issues?label_name%5B%5D=Good+First+Issue)
Nathan McCarty's avatar
Nathan McCarty committed
47

48
These are issues expected to give a good introduction to the repository. They are most often easy issues that require little to no understanding of the project to start hacking on.
Nathan McCarty's avatar
Nathan McCarty committed
49

50
New contributors are encouraged to go for issues with the `Good First Issue` tag first, and then move up to `D-EASY` as they grow more comfortable with the project. Though, this is not a hard guideline, if you want to jump straight in, feel free to grab a `D-MEDIUM` or `D-HARD` and contact @ThatOneLutenist or ask in one of the chats if you get stuck or need mentoring.
Nathan McCarty's avatar
Nathan McCarty committed
51

Nathan McCarty's avatar
Nathan McCarty committed
52 53 54
Additionally, we have a more general [`Help
Wanted`](https://gitlab.com/asuran-rs/asuran/-/issues?label_name%5B%5D=Help+Wanted) tag, that denotes issues that I have identified as one I would epically appreciate assistance with.

55 56
Primer on our development procedures
------------------------------------
Nathan McCarty's avatar
Nathan McCarty committed
57

58
Asuran development works on two major branches, `master` and `dev`. `master` is our 'stable' branch where we apply strict code quality standards and all tests must pass all the time.
Nathan McCarty's avatar
Nathan McCarty committed
59

60
`dev` is a much looser experience, it is our "move fast and break things" branch. Code commuted to dev may require further cleanup, like minor refactoring or addition of tests, before hitting master, but it is still expected to eventually hit master.
Nathan McCarty's avatar
Nathan McCarty committed
61

Nathan McCarty's avatar
Nathan McCarty committed
62 63 64 65 66
Coding Conventions
------------------

Please take a look at our [Coding Conventions](CONVENTIONS.md) for guidelines and coding conventions used in this repository.

67 68
Pull request check list
-----------------------
Nathan McCarty's avatar
Nathan McCarty committed
69

70 71 72
We rigorously verify all code committed to the `master` branch, but don't let that scare you. If you aren't quite there yet, go ahead and submit your pull request. Someone will either help you get your code up to where it needs to be to hit `master`, or pull it into the `dev` branch for cleanup by another contributor.

All contributions are welcome, don't feel like you have to write the most beautiful code of your life before you hit that create pull request button.
Nathan McCarty's avatar
Nathan McCarty committed
73 74

All pull requests should do the following things before landing on master:
75 76 77 78 79 80 81

-	[ ] Compile
-	[ ] Pass clippy
-	[ ] Pass all tests
-	[ ] Not reduce test coverage by a needless amount
-	[ ] Have reasonably good doc comments
-	[ ] Add tests for the new behavior if it is more than trivially complex
Nathan McCarty's avatar
Nathan McCarty committed
82 83 84

Contributions to the `dev` branch have a much simpler check list they must complete:

85 86 87 88 89
-	[ ] Code must compile
-	[ ] PR must be associated with a tracking issue

Code of Conduct and Licensing
-----------------------------
Nathan McCarty's avatar
Nathan McCarty committed
90

91
All contributers to this project are bound by the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct).
Nathan McCarty's avatar
Nathan McCarty committed
92

93
By contributing to this project, you agree to license your contribution under the [BSD 2 Clause + Patent](LICENSE) license.