1# How to contribute?
2
3If you are reading this, chances are you want to contribute to the Renode project, and that is already great news.
4
5Note that you must sign a Contributor License Agreement (CLA) in order to contribute to this project.
6
7Please read the short manual below where we provide some simple guidelines for a good cooperation experience.
8
9## Issues
10
11Issues in the Renode project are tracked in the [GitHub issues system](https://github.com/antmicro/renode/issues).
12
13We also use an internal issue tracker, so it is possible that some referenced issues are not publicly available.
14
15Please create an issue even if you plan to fix it (instead of creating a merge request directly - see below).
16
17If you are reporting a bug, the best way to ensure it's reproducible is by using Renode's [Issue reproduction template](https://github.com/renode/renode-issue-reproduction-template).
18Use this repo template to create a setup that reproduces your use cases and fails a test.
19This will ensure we're able to understand the bug you're experiencing and will help us react faster.
20
21If you'd like to file a feature request, then just carefully describe what you need - the more background and precise suggestions you provide, the higher the chance that someone will be able to implement it.
22
23If, for some reason, it's impossible to create a reproduction repo for your issue, please ensure you provide all of the following:
24
25* the platform you are using (MacOS, Windows, Linux, what distro/version?)
26* the Renode version you are using
27* the exact platform you are trying to run (`.resc` and `.repl` files or links to those if you are using default ones)
28* preferably, the source code of your binary with build instructions - or at least a binary.
29
30We know in some cases users are not able to share the full source code of the binary they are trying to run.
31In this case you may try to isolate the problem to some smaller example which is not problematic to share, or at least share a binary.
32
33Otherwise you can of course contact us at [support@renode.io](mailto:support@renode.io) and provide what is needed under an NDA.
34
35## Pull requests
36
37If you plan to fix an issue by yourself, you should use the [GitHub pull requests mechanism](https://github.com/antmicro/renode/pulls).
38To do that, you need to:
39
40* create a fork of our repository on your account (if you haven't done it already)
41* create a branch based on the current `master` branch with the following name:
42
43  `NUMBER_OF_TICKET-short_name_of_the_issue`, for example `1234-invalid_instruction_wfi`
44* write and commit your code (see sections below)
45* if your pull request is about to fix an issue or add a new feature, use Renode's [Issue reproduction template](https://github.com/renode/renode-issue-reproduction-template) and try to prepare two branches - one that fails a test and one that includes your fix and passes the same test
46* create a pull request to our Renode repository with the proposed fix.
47
48Your merge request will then be reviewed by the Renode team, and potentially a discussion on GitHub will ensue.
49
50We might ask you to do some fixes or write a test for your change, but this is only meant to keep code quality high(er).
51
52If this is your first contribution to Renode, you will also be asked to sign our Contributor License Agreement, which you can do directly from within the Pull Request in question.
53
54After you sign the CLA and our team performs a final review of your code, it will be merged to the Renode master branch.
55
56## Committing
57
58### Guidelines
59
60We recommend small commits.
61Note that while small commits can always be squashed together, dividing commits is not that straightforward.
62
63For example if for the issue to be fixed you need to correct two classes without changing their public interface, do it in two separate commits.
64Also if the change as a whole is big, it is easier to review it afterwards if it is divided into parts similar to the way the original author introduced the changes.
65If you change some names and behaviour in the same commit, it is hard to tell which changes apply where.
66
67If you are fixing some formatting issue, please take care to separate these changes from any logic-related commits.
68You don't have to split formatting of different files into different commits, however, formatting changes are best done simultaneously for coherence.
69
70It is vital to have all the code compiling without errors after each commit - this is useful for bisecting.
71
72### Commit messages
73
74Here is a proposed format of the commit message:
75
76```
77[#1234] optional-tag: Short description of a commit
78
79If you feel that the commit needs a bit more explanation than
80a short description you can put all your thoughts here (after
81a blank line).
82```
83
84`#1234` is obviously the number of the GitHub issue that describes the problem you're trying to fix.
85As we use an internal issue tracker, you may observe that some issue numbers (over #5000) are not pointing to any GitHub issue.
86
87The short description is just a short sentence describing changes introduced by a commit.
88If you have problems to formulate a single sentence (because the commit makes a lot of changes) than perhaps you should consider splitting it into several independent commits (as noted above).
89We usually write these descriptions in a form of a sentence, in imperative mood, starting with a capitalized letter.
90
91You can add an optional tag word before the commit message - it is especially useful if you have a series of commits related to the same topic (e.g. changes in one peripheral model).
92
93The long description is not obligatory, but nice to have.
94There is no word limit here, but we all should be reasonable.
95Discussions and long analyses should be placed in the GitHub issue system.
96
97## Code formatting and quality
98
99As we use Monodevelop for development, we rely on its formatting engine.
100Each project and solution contains settings for the Monodevelop formatter.
101If you use another editor, you may read the `.csproj` file and apply these rules by hand, as they are written in a readable format.
102
103Please do not introduce formatting that is strictly inconsistent with other files.
104
105Do not use `regions` to separate categories of methods/fields in your classes.
106We usually try to keep the classes' API at the top, and the gory stuff below.
107
108The rule of thumb is:
109
110* public before protected before private
111* static before instance
112* constructor before method before property before field before constant
113* all inner types at the end.
114
115As this list does not cover all possible options, you may be asked to fix something during review.
116