Working with GitHub - LArSoft/larsoft_docs GitHub Wiki

Working with GitHub

{{>TOC}}

Overview

The reference copy of LArSoft is hosted on GitHub under the LArSoft organization. The process of checking out LArSoft repositories from GitHub is nearly identical to that formerly used to check out repositories from Redmine.

The steps required to commit code to the develop branch of LArSoft repositories are:

  • Check out relevant repositories
  • Create a feature branch from develop or from a tagged release
  • Make local changes to code in the feature branch
  • Test changes against code at the head of develop

At this point, 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 forked 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 . The build is carried out by the CI system
  • Running the usual unit tests and continuous integration tests
  • Upon successful completion of the tests, approval by a “Level 1” manager that triggers an automated merge of the code to the develop branch. (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

An pull request testing and approval workflow

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

General references on using GitHub (not LArSoft specific)

Working notes (mostly archival)

  • Lynn's notes (old – there is better information above)
    • These are working notes that will eventually be integrated with the official pages.
  • The GitHub migration plan
⚠️ **GitHub.com Fallback** ⚠️