Working with GitHub » History » Version 24

Version 23 (Erica Snider, 01/14/2020 01:31 PM) → Version 24/27 (Erica Snider, 01/22/2020 02:32 PM)

h1. Working with GitHub


h2. Overview

The reference copy of LArSoft is will soon be hosted on GitHub under the LArSoft organization. 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 formerly 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 remains remain the same:

* 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, 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 @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.

h2. Detailed information, instructions and resources

* An [[pull request testing and approval workflow|overview of the pull request testing and approval process]]

* For LArSoft users and developers: how to check out repositories, requirements and steps to submit changes, move existing code
** [[WorkingWithLArSoftGithubRepos|The basics of working with LArSoft GitHub repositories]]
** [[Migrating_Redmine_Feature_Branches|Moving an existing Redmine feature branch to GitHub]]

* For Level 1 and Level 2 managers / approvers: procedures for managing and approving pull requests
** [[Executing_the_pull_request_approval_workflow|Executing the pull request approval workflow]]
** [[Pull_request_comments_that_trigger_CI_actions|Pull request comments that trigger CI actions]]
** [[Github_labels_used_to_indicate_pull_request_status|Github labels used to indicate pull request status]]

* For people who maintain the approval workflow
** [[Maintaining_CMSbot_scripts_and_Jenkins_jobs|Maintaining the LArSoft fork of CMSbot scripts and Jenkins GitHub Integration jobs at FNAL]]

* For new experiments / projects seeking to customize and use the pull request approval workflow system
** [[SetupCMSbotScriptsYourOrg|Setting the LArSoft fork of CMSbot for your organization/repo]]

* Working notes
** [[Lynn's notes]]
*** These are working notes that will eventually be integrated with the official pages.
** The [[GitHub migration plan]]