GitHub

Contributing to JetReconstruction

Thank you for your interest in contributing to JetReconstruction.jl. We are very happy to get contributions for:

  • Bug reports, for things that don't work properly.
  • Feature requests, for things that JetReconstruction.jl could do in the future.
  • Documentation improvements, for things that could be better explained.

We ask all contributors to follow the Julia Community Standards - thank you!

Issues: Bug Reports, Suggestions, Questions

Raise bug reports and general issues using the issues feature. For bug reports make sure that you:

  • are using the latest released version
  • explain how you are running the code
  • state what the problem is clearly
  • say what you would expect the behaviour to be

New Features and Pull Requests

If you would like to contribute a new feature to the package it is a good idea to open an issue first, so that you can discuss with the maintainers and check that the feature is in-scope and general enough to warrant direct implementation (as opposed to developing an extension package).

There are a few points to bear in mind for development listed below.

Develop against main

Do your development against the head of the main branch so that your code will work with all the other features that are in development at the moment. If main is targetting a breaking change release, e.g., v0.X+1.0 where v0.X is the current version there may be a case for targetting the release-0.X branch if your PR is a bug fix. Please discuss this with the maintainers.

If it takes a while to develop or implement review changes, rebase against main as needed.

Documentation

  • Document all public functions and types using Julia docstrings that will be useful to users.
    • Add docstrings for internal functions too (unless these are trivial) with a focus on helping fellow developers.
  • Update or add relevant sections in the documentation under docs/src/ as needed.
  • Provide clear explanations and usage examples where appropriate.

Tests

  • All new features must include tests in test/.
  • The pattern used for implementation is to write a test in test/test-NEW-FEATURE.jl so that the test can be run standalone, and to add an include("test-NEW-FEATURE.jl") into runtests.jl for the CI.
  • To validate the output for a new feature store reference output (e.g., generated by similar functionality in Fastjet) into test/data. Zstd compression is recommended (see the open_with_stream() helper for making this transparent).
  • Ensure tests cover edge cases and typical usage.
  • Run ] test JetReconstruction or julia --project test/runtests.jl before submitting your PR to verify all tests pass.

Examples

  • Add or update usage examples in the documentation or in the examples directory.
  • If your examples require extra packages, e.g., graphics or statistics, please put them into a subdirectory (examples/FEATURE/...) with their own Project.toml.
  • Examples should be minimal, clear, and runnable.

Formatting

The code in this repository is formatted with JuliaFormatter. Currently we use version 1 of the formatter so please use this too or the CI may complain.

Bootstrap

This is one way to do it:

$ julia --project=@juliaformatter
] add JuliaFormatter
] compat JuliaFormatter 1.0
] update

$ julia --project=@juliaformatter -e 'using JuliaFormatter; format(".")'

Communication

  • Open an issue to discuss major changes before starting work.
  • Be responsive to feedback during the review process.

Pull Request Checklist

Before submitting a PR, please ensure:

  • [ ] Code is formatted and linted.
  • [ ] All public APIs are documented.
  • [ ] New/modified code is covered by tests.
  • [ ] Examples are provided or updated.
  • [ ] All tests pass locally.

Some Development Tips

As far as possible we follow standard best practice for Julia code. In particular you should be familiar with the following guidelines:

In addition, here are a few common issues we have seen that you should avoid:

Don't use an abstract struct if you are the only sub-type

If you want to define functionality in a holistic way with many variables then using a struct is very natural. However, you should not define an abstract super type for your struct unless there will be multiple concrete types.

Don't define accessor methods for internal variable access

To access struct data, when this is only used internally, just access the member variable directly. Accessors should only be needed if:

  • This is data a user would want to access, in which case the accessor shields the implementation details.
  • There are many sub-types and an accessor helps to optimise data retrieval.

Thank you for helping improve JetReconstruction!