Skip to content

Commit 1ce3921

Browse files
graeme-a-stewartgraeme-a-stewart
authored
Add contribution guide (#158)
* Add contribution guide Add a contribution guide for the project. This is written in the package documentation, but is linked from the standard CONTRIBUTING.md. Added style guid and performance tips, as well as avoiding some errors we have commonly seen. Specify explicitly that the Julia Community Code of Conduct should be adhered to. Enforcement mechanism needs to be decided upon.
1 parent 6815915 commit 1ce3921

File tree

4 files changed

+140
-0
lines changed

4 files changed

+140
-0
lines changed

‎CODE_OF_CONDUCT.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Code of Conduct
2+
3+
We ask all contributors to `JetReconstruction.jl` to follow the [Julia Community
4+
Standards](https://julialang.org/community/standards/) - thank you!

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Contributing to JetReconstruction
2+
3+
Please see the [*Contributing*](https://juliahep.github.io/JetReconstruction.jl/dev/contributing/) section of the documentation.

‎docs/make.jl‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ makedocs(sitename = "JetReconstruction.jl",
1919
"Jet Helpers" => "helpers.md",
2020
"EDM4hep" => "EDM4hep.md",
2121
"Visualisation" => "visualisation.md",
22+
"Contributing" => "contributing.md",
2223
"Reference Docs" => Any["Public API" => "lib/public.md",
2324
"Internal API" => "lib/internal.md"],
2425
"Extras" => Any["Serialisation" => "extras/serialisation.md"]

‎docs/src/contributing.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Contributing to JetReconstruction
2+
3+
Thank you for your interest in contributing to `JetReconstruction.jl`. We are
4+
very happy to get contributions for:
5+
6+
- Bug reports, for things that don't work properly.
7+
- Feature requests, for things that `JetReconstruction.jl` could do in the future.
8+
- Documentation improvements, for things that could be better explained.
9+
10+
We ask all contributors to follow the [Julia Community
11+
Standards](https://julialang.org/community/standards/) - thank you!
12+
13+
## Issues: Bug Reports, Suggestions, Questions
14+
15+
Raise bug reports and general issues using the
16+
[*issues*](https://github.com/HSF/JetReconstruction.jl/issues) feature. For bug
17+
reports make sure that you:
18+
19+
- are using the latest released version
20+
- explain how you are running the code
21+
- state what the problem is clearly
22+
- say what you would expect the behaviour to be
23+
24+
## New Features and Pull Requests
25+
26+
If you would like to contribute a new feature to the package it is a good idea
27+
to open an issue first, so that you can discuss with the maintainers and check
28+
that the feature is in-scope and general enough to warrant direct implementation
29+
(as opposed to developing an extension package).
30+
31+
There are a few points to bear in mind for development listed below.
32+
33+
### Develop against `main`
34+
35+
Do your development against the head of the `main` branch so that your code will
36+
work with all the other features that are in development at the moment. If
37+
`main` is targetting a breaking change release, e.g., `v0.X+1.0` where `v0.X` is
38+
the current version there may be a case for targetting the `release-0.X` branch
39+
if your PR is a bug fix. Please discuss this with the maintainers.
40+
41+
If it takes a while to develop or implement review changes, rebase against
42+
`main` as needed.
43+
44+
### Documentation
45+
46+
- **Document all public functions and types** using Julia docstrings that will
47+
be useful to users.
48+
- Add docstrings for internal functions too (unless these are trivial) with
49+
a focus on helping fellow developers.
50+
- Update or add relevant sections in the documentation under `docs/src/` as needed.
51+
- Provide clear explanations and usage examples where appropriate.
52+
53+
### Tests
54+
55+
- All new features **must include tests** in `test/`.
56+
- The pattern used for implementation is to write a test in
57+
`test/test-NEW-FEATURE.jl` so that the test can be run standalone, and to add
58+
an `include("test-NEW-FEATURE.jl")` into `runtests.jl` for the CI.
59+
- To validate the output for a new feature store reference output (e.g.,
60+
generated by similar functionality in Fastjet) into `test/data`. Zstd
61+
compression is recommended (see the `open_with_stream()` helper for making
62+
this transparent).
63+
- Ensure tests cover edge cases and typical usage.
64+
- Run `] test JetReconstruction` or `julia --project test/runtests.jl` before
65+
submitting your PR to verify *all* tests pass.
66+
67+
### Examples
68+
69+
- Add or update usage examples in the documentation or in the `examples` directory.
70+
- If your examples require extra packages, e.g., graphics or statistics, please put them into a subdirectory (`examples/FEATURE/...`) with their own `Project.toml`.
71+
- Examples should be minimal, clear, and runnable.
72+
73+
### Formatting
74+
75+
The code in this repository is formatted with
76+
[`JuliaFormatter`](https://github.com/domluna/JuliaFormatter.jl). Currently we
77+
use *version 1* of the formatter so please use this too or the CI may complain.
78+
79+
#### Bootstrap
80+
81+
This is one way to do it:
82+
83+
```sh
84+
$ julia --project=@juliaformatter
85+
] add JuliaFormatter
86+
] compat JuliaFormatter 1.0
87+
] update
88+
89+
$ julia --project=@juliaformatter -e 'using JuliaFormatter; format(".")'
90+
```
91+
92+
### Communication
93+
94+
- Open an issue to discuss major changes before starting work.
95+
- Be responsive to feedback during the review process.
96+
97+
### Pull Request Checklist
98+
99+
Before submitting a PR, please ensure:
100+
101+
- [ ] Code is formatted and linted.
102+
- [ ] All public APIs are documented.
103+
- [ ] New/modified code is covered by tests.
104+
- [ ] Examples are provided or updated.
105+
- [ ] All tests pass locally.
106+
107+
## Some Development Tips
108+
109+
As far as possible we follow standard best practice for Julia code. In
110+
particular you should be familiar with the following guidelines:
111+
112+
- [The Julia Style Guide](https://docs.julialang.org/en/v1/manual/style-guide/)
113+
- [Julia Performance Tips](https://docs.julialang.org/en/v1/manual/performance-tips/)
114+
115+
In addition, here are a few common issues we have seen that you should avoid:
116+
117+
### Don't use an abstract struct if you are the only sub-type
118+
119+
If you want to define functionality in a holistic way with many variables then
120+
using a struct is very natural. However, you should not define an abstract super
121+
type for your struct unless there will be multiple concrete types.
122+
123+
### Don't define accessor methods for internal variable access
124+
125+
To access struct data, when this is only used internally, just access the member
126+
variable directly. Accessors should only be needed if:
127+
128+
- This is data a user would want to access, in which case the accessor shields
129+
the implementation details.
130+
- There are many sub-types and an accessor helps to optimise data retrieval.
131+
132+
*Thank you for helping improve JetReconstruction!*

0 commit comments

Comments
 (0)