Working with GitHub¶
The reference copy of LArSoft will soon be hosted on GitHub. Read-only mirror copies of the repositories will be maintained on Redmine. In this scheme, the process of checking out LArSoft repositories from GitHub will be nearly identical to that used to check out repositories from Redmine.
Some of the steps to required to commit code to the
develop branch of LArSoft repositories will also remain the same:
- Check out relevant repositories
- Create a feature branch from
developor from a tagged release
- Make local changes to code in the feature branch
- Test changes against code at the head of
At this point, however, developers must initiate a pull-request for the specific change to be merged, since most users will not have privilege to commit directly to the LArSoft repositories on GitHub. In order to create a pull request, a person must first:
- Have a properly configured personal GitHub account
- Push the feature branch to the cloned LArSoft repositories in their personal GitHub account
Creating the pull request then triggers a workflow that includes:
- An automated and manual check of the code in the proposed change by a "Level 2" manager from one of the experiments. (Check with your experiment's offline organization to identify who the Level 2 managers are for your experiment.)
- Building the code against the head of
develop(as is currently required). The build is carried out by the CI system
- Running the usual unit tests and continuous integration tests (as is currently required)
- Upon successful completion of the tests, approval by a "Level 1" manager that triggers an automated merge of the code to the
developbranch. (See the roles page to identify the LArSoft Level 1 managers)
Note that only Level 1 managers have write privilege to the central repositories.
The next section provides detailed information on each of the above steps, as well as information about the roles and procedures, and how to move an existing branch from a Redmine repository to GitHub.
Detailed information, instructions and resources¶
- For LArSoft users and developers: how to check out repositories, requirements and steps to submit changes, move existing code
- For Level 1 and Level 2 managers / approvers: procedures for managing and approving pull requests
- For people who maintain the approval workflow
- For new experiments / projects seeking to customize and use the pull request approval workflow system
- Working notes
- Lynn's notes
- These are working notes that will eventually be integrated with the official pages.