Warning, /EICrecon/CONTRIBUTING.md is written in an unsupported language. File is not indexed.
0001 # Contribution Guidelines
0002
0003 EICrecon is a collaborative software project, and contributions from anyone are welcome.
0004 This document describes the recommended workflow for developing and reviewing contributions to EICrecon. Questions about any step of the process can be directed to the review team, which can be contacted via email:
0005
0006 Email: epic-software-review@lists.bnl.gov
0007
0008 ## How to contribute
0009
0010 The following steps describe the recommended workflow for contributing to EICrecon.
0011
0012
0013 ```mermaid
0014 flowchart LR
0015 A(["Plan/Communicate"])
0016 A --> B(["Create draft PR"])
0017 --> C(["Develop self-contained commits"])
0018 --> D(["Ready for review"])
0019 --> E(["Timescale for review"])
0020 ```
0021
0022 1. Communicate your development plans with the Reconstruction Framework and Algorithms or Physics and Detector Simulations Working Groups before beginning development. This helps clarify the scope and expected timeline.
0023
0024 2. Create a draft PR as soon as work begins. You may request a reviewer directly, or ask the review team to assign one. If the assigned reviewer cannot complete the review, they should request a new reviewer from the review team.
0025
0026 3. Develop your code using concise commits with descriptive commit messages.
0027
0028 #### Development workflow
0029
0030 The following recommendations describe how to develop a contribution within EICrecon.
0031
0032 * Start each development in a new branch.
0033 * Use atomic commits, and commit frequently.
0034
0035 - Each commit should reflect a single self-contained change. Try to avoid overly large commits (bad examples are for instance mixing logical change with code cleanup and typo fixes).
0036
0037 * Write descriptive commit messages to preserve development history. See e.g. [here](https://wiki.openstack.org/wiki/GitCommitMessages#Information_in_commit_messages) for more information.
0038 * Try to keep PRs as small as possible, so that each PR belongs to one logically/conceptually different development. This simplifies the code review process.
0039
0040 4. When the code is ready for review, mark the pull request as **Ready for Review** to notify the reviewer.
0041
0042 5. The reviewer should provide a timescale for their review without delay during working hours (depending on the scope and size of the PR and on collaboration schedule).
0043
0044 ### PR checklist
0045
0046 A PR is ready to be reviewed when:
0047
0048 - [x] A detailed description of the PR is provided
0049 - [x] All CI jobs pass
0050 - [x] clang-tidy and clang-format have been run locally (see the [Code style and standards](#code-style-and-standards) section for instructions)
0051 - [x] There is a legible commit history
0052 - [x] Code is appropriately documented
0053
0054 ## Reviewing other contributions
0055
0056 Upon the code being marked ready for review, the review period for the PR begins. ePIC requires every PR submitted to EICrecon to receive at least one review before being marked ready to merge. Reviewers and all collaborators of ePIC are expected to abide by the ePIC [code of conduct](https://www.epic-eic.org/collaboration/professional.html). The reviewer should evaluate the following criteria:
0057
0058 #### Approving a pull request
0059
0060 - Does the PR have a description that reflects the content of the code?
0061 - Does the CI pass?
0062 - Is the contributed code:
0063 - maintainable and sustainable?
0064 - (if applicable) correct in satisfying physics requirements and maintaining downstream assumptions?
0065 - scalable (i.e. it can run in production)?
0066 - Are relevant performance benchmarks considered? And if changes in computing and/or physics performance are observed, are they discussed and understood?
0067 - Have all comments raised by collaborators/reviewers been addressed?
0068
0069 ## Code style and standards
0070
0071 EICrecon uses clang-format for formatting the source code. Your code can be formatted automatically using the .clang-format file.
0072 - class names: PascalCase
0073 - Base namespace: eicrecon
0074 - Indent: 2 spaces
0075 - File naming:
0076
0077 - File extensions: .cc, .h
0078 - Algorithm config name: <AlgorithmName>Config.h
0079 - Factory name: <AlgorithmName>_factory.h
0080 - Templated classes end with "T" (classes inheriting from them should not use the T suffix unless they are also templates)
0081 - For more details see [.clang-format](https://github.com/eic/EICrecon/blob/main/.clang-format)
