tutorial-jana2/episodes/05-contributing.md

0001 ---
0002 title: "Contributing code changes to the EICrecon repository"
0003 teaching: 10
0004 exercises: 10
0005 ---
0006
0007 ::::::::::::::::::::::::::::::::::::::::::::: questions
0008
0009 - How do I submit code to the EICrecon repository?
0010
0011 :::::::::::::::::::::::::::::::::::::::::::::
0012
0013 ::::::::::::::::::::::::::::::::::::::::::::: objectives
0014
0015 - Understand naming conventions for EICrecon.
0016 - Submitting a Pull Request for a contribution to EICrecon.
0017
0018 :::::::::::::::::::::::::::::::::::::::::::::
0019
0020 ## Repository
0021
0022 We use GitHub as the main code repository tool. The repositories are located:
0023
0024 - [EICrecon](https://github.com/eic/EICrecon) - EIC reconstruction algorithms and EIC-related code for JANA framework
0025 - [JANA2](https://github.com/JeffersonLab/JANA2) - The core framework
0026
0027 If you hesitate where to file an issue or a question, then the most probably it should be done in EICrecon project. Use the [EICrecon issues](https://github.com/eic/EICrecon/issues) tracker to file bug reports and questions.
0028
0029 There is also [EICrecon project board](https://github.com/orgs/eic/projects/6/views/1) where one can see what issues are in work and what could be picked up.
0030
0031 ::::::::::::::::::::::::::::::::::::::::::::: challenge
0032
0033 ## Exercise
0034
0035 - Go to the [EICrecon project board](https://github.com/orgs/eic/projects/6/views/1) and see what tickets are marked as "TODO".
0036
0037 ::::::::::::::: solution
0038
0039 The project board groups issues into columns such as "TODO", "In Progress", and "Done". The "TODO"
0040 column lists issues that are ready to be picked up. Any of these is a reasonable starting point for
0041 a first contribution.
0042
0043 :::::::::::::::
0044
0045 :::::::::::::::::::::::::::::::::::::::::::::
0046
0047 ## Contributing workflow
0048
0049 - A workflow starts from creating an issue with a bug report or a feature request. It is important to create an issue even if the subject was discussed on a meeting, personally, etc.
0050
0051 - Then create a branch out of the issue.
0052
0053   ![Create branch from issue](fig/contributing/create_branch_1.png){alt="Creating a branch from a GitHub issue, step 1"}
0054
0055   ![Create branch from issue](fig/contributing/create_branch_2.png){alt="Creating a branch from a GitHub issue, step 2"}
0056
0057 - After you commit and push changes to the branch, create a pull request (PR). As soon as PR is created a continious integration (CI) system will run to test the project compiles and runs on EIC environment. Any further push to this branch will trigger CI rerun the tests and check if merge is ready to be done. PRs are also a good place do discuss changes and code with collaborators. So it might be reasonable to create a PR even if not all work on issue is done. In this case create a Draft PR.
0058
0059   ![Create branch from issue](fig/contributing/create_branch_3.png){alt="Opening a pull request from the new branch"}
0060
0061   ![Create branch from issue](fig/contributing/create_branch_4.png){alt="Filling in the pull request information"}
0062
0063   To summarize:
0064
0065   - Create PR
0066   - Fill the information
0067   - Use "Draft PR" if the work is not done
0068   - Assign a reviewer
0069
0070 - Before accepting the Pull Requiest code goes through a code review by one of the core developers. If you need someone particular to review your changes - select the reviewer from the menu. Otherwise one of the developers will review the code and accept the PR.
0071
0072 More on the EIC contribution guide is in the [Setting up your environment tutorial](https://eic.github.io/tutorial-setting-up-environment/), [video](https://youtu.be/Y0Mg24XLomY?list=PLui8F4uNCFWm3M3g3LG2cOledhI7IvTAJ)
0073
0074 ## Coding style
0075
0076 One can find coding style and other contributins policies at [CONTRIBUTING.md](https://github.com/eic/EICrecon/blob/main/CONTRIBUTING.md). It is yet to be finished but one can find current decisions on coding style there
0077
0078 ## References
0079
0080 - [EICrecon](https://github.com/eic/EICrecon)
0081 - [EICrecon project board](https://github.com/orgs/eic/projects/6/views/1)
0082 - [EICrecon issues](https://github.com/eic/EICrecon/issues)
0083 - [JANA2](https://github.com/JeffersonLab/JANA2)
0084 - [EIC environment - youtube](https://youtu.be/Y0Mg24XLomY?list=PLui8F4uNCFWm3M3g3LG2cOledhI7IvTAJ)
0085 - [EIC environment - tutorial](https://eic.github.io/tutorial-setting-up-environment/)
0086
0087 ::::::::::::::::::::::::::::::::::::::::::::: keypoints
0088
0089 - Write code in a style consistent with the rest of the repository.
0090 - Contributions should be made through the GitHub Pull Request mechanism.
0091
0092 :::::::::::::::::::::::::::::::::::::::::::::