CONTRIBUTING.md 5.45 KB
Newer Older
1
2
For contributing to Spoon, the recommended way is to create a pull request (PR) on Github. Upon acceptance, the merged code is copyrighted under the [Cecill-C license](http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html).

3
4
5
The integrator code of conduct
------------------------------

6
The integrators are the developers who have write access to the repository. The integrators shall respect the following rules:
7
8
9

* Spoon integrators only merge atomic pull requests (single bug fix or single feature)
* Spoon integrators only merge well tested and well documented pull requests, after thorough code review
10
* Spoon integrators check the quality of the squashed merge commit message, and change it if required. The convention is that it starts with `fix:`, `feat:`, `test:`, `doc:`, `perf:`, `chore:`, `refactor:`, `checkstyle:` ([source](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#type)). Optionally the impacted component can be specified, eg `fix(prettyprinter): ...`.
11
12
13
14
15
* Spoon integrators never push directly to `master`
* Spoon integrators  never merge their own pull request
* Spoon integrators leave pull requests opened at least 1 day before merging, so that the community is aware and can comment on them
* Serious conflicts, who cannot be resolved by time and discussion, are resolved by a vote among integrators.

16
17
How to become integrator? The integrators are the developers who have made significant contributions over the last 12 months (gliding window). Significance is assessed by the current set of integrators who co-opt the new ones.

18
Current integrators:
19

20
- Simon Larsén [@slarse](https://github.com/slarse/)
21
- Nicolas Harrand [@nharrand](https://github.com/nharrand/)
22
- Martin Monperrus [@monperrus](https://github.com/monperrus/)
23
- Martin Wittlinger [@MartinWitt](https://github.com/MartinWitt)
24
25
26

Guidelines for pull requests
----------------------------
27

28
There are different kinds of pull-requests, in particular bug-fix, new features, refactoring and performance pull-requests.
29

30
Guidelines for all pull-requests:
31

32
33
34
* The pull request does a single thing (eg a single bug fix or a single feature). 
* The pull request must pass all continuous integration checks (incl. formatting rules).
* The pull request must have an explicit and clear explanation.
35
* If the pull request resolves an issue, simply add "fix #issueNumber" or "close #issueNumber" to the description, see [doc](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue) for details
36
37
38
39
* Pull-request title:
  * The pull-request title starts with a prefix stating its kind: "fix:", "feature:", "refactor:", "perf:", "checkstyle:"
  * Pull-requests that are in progress are prefixed by "WIP".
  * Pull-requests that are ready for review are prefixed by "review", or labeled as "[review](https://github.com/INRIA/spoon/labels/review)".
40
41
42
43
* **Avoid force-pushing** after you have marked your PR as ready for review or have received any form of feedback on your PR.
  * While a clean and clear commit history can help in reviewing a PR, it's confusing for reviewers to have previously reviewed commits disappear.
  * Note that PRs are squashed. Don't worry if the commit history becomes a bit convoluted as you iterate on the PR after receiving feedback.
  * It's OK to force-push to WIP PRs as long as you are not collaborating with anyone.
44
* **Your contribution is highly welcome**! If you have anything interesting, then we welcome your PR even if it is not perfect at the beginning. The Spoon community will help you to fix the remaining problems, if any.;-)
45
46
47
48
* **JUnit version:** 
  * [PR to migrate existing tests from JUnit4 to JUnit5 are welcome](https://github.com/INRIA/spoon/issues/3919).
  * New test classes must use JUnit5.
  * Adding test cases to existing JUnit4 test classes is OK, but try to stick to the very basics (if possible, only use the `@Test` annotation)
49
50
  
Guidelines for bug-fix pull-requests:
51

52
* The pull request must contain a test case highlighting the bug. 
53

54
Guidelines for feature pull-requests:
55

56
57
* The pull request must contain a set of test case to specify the expected behavior of the new feature. 
* The pull request must contain an update in the documentation folder (`doc`) to explain the new feature.
58
* The pull request must pass all architectural rules that are checked in [SpoonArchitectureEnforcerTest](https://github.com/INRIA/spoon/blob/master/src/test/java/spoon/test/architecture/SpoonArchitectureEnforcerTest.java) (eg new packages must be registered there)
59

60
Other kinds of pull-requests:
61

62
1. Pull requests with passing test cases only are welcome, they specify previously unspecified behavior and are prefixed by "test:".
63
1. Pull requests with failing test cases only are welcome, they reproduce bugs and are very useful for maintainers to fix them. You can prevent failing the CI with adding the annoation `@Ignore("UnresolvedBug")` and `@GitHubIssue(issueNumber = <your-issue-number>)`.
64
1. "Chore" pull-requests modify the CI setup.
65
1. If there is no activity on an issue or on a pull request for 3 months it's closed.
66

67
68
Public API
----------
69

70
71
72
73
74
75
The public API is composed of all public classes and methods, except those for which at least one of the following condition holds:

* annotated with @Internal
* located in a package called `internal`, including all subpackages, that is `**.internal.**`

Classes annotated with `@Experimental` are planned to in the public API in the future, but are still considered unstable and can change in non-backward compatble manner.