non-EPICS packages go to https://github.com/slaclab

EPICS modules go to https://github.com/slac-epics

We are using this spreadsheet to control the items already migrated, with a check-list: https://docs.google.com/spreadsheets/d/1gPJsr9UuHfTCUX56W0CS8fwJUE3NL1A-21IHwAp1U1A/edit#gid=0

1. Cleanup branches

We don't want to send all available branches to GitHub. The first step is to go over all the branches and check with branch owners whether they can be merged or deleted. Depending on how many people are involved, this can take a long time.

2. Check if there are commits pending push

Contact all previous developers and tell them that the repository will move to GitHub. Ask them to push commits that are pending, otherwise, they will need to change the remotes later.

3. For SLAC-created software, rename "master" and create "pre-release"

This doesn't apply to software modified from code external to SLAC.

We want the main branch to be called "main", not "master" and we need a "pre-release" branch.

This is the recipe to rename master:

git branch -m master main
git push -u origin main
cd to bare repo in AFS
git symbolic-ref HEAD refs/heads/main
cd back to local repo
git push origin -d master

If the "pre-release" branch doesn't exist, create it in the same commit as "main". Push the pre-release branch to the repo still in AFS.

4. For SLAC-created software, apply the license files and headers

This doesn't apply to software modified from code external to SLAC.

Download the license file somewhere outside your local repository: https://github.com/slaclab/surf/blob/pre-release/LICENSE.txt

Download the script that applies the license somewhere outside your local repository: https://github.com/slaclab/surf/blob/pre-release/scripts/apply_slac_license.py

Check the arguments for the script:

$ python apply_slac_license.py -h
Usage: apply_slac_license.py root_dir module_name [optional path_to_license]

root_dir is the software $TOP directory.

module_name is needed because it will be added to the headers.

path_to_license is needed. Just provide a path for the license file that you downloaded.

Make sure the local repo has pre-release checked-out, not main.

After applying the license:

1. Commit. Make sure it is in the pre-release branch.
2. Push, still to AFS.

5. Create a repository in the proper GitHub organization

You will need to use GitHub's web system to create the repository or the github CLI tool. A couple of rules:

• Public repository for software that has SLAC's license file and headers.
• Private repository otherwise.
• Don't create a README.md file.

6. Send the repository to GitHub

Replace <organization> and <repo> with the proper names in the recipe below. You will need to push every branch that you need. Below is just an example for code created at SLAC, but customized code from the community will have different branches than this example. Don't forget to add --tags to the push command.

git remote add github-origin https://github.com/<organization>/<repo>.git
git push -u github-origin main --tags
git push github-origin pre-release --tags

7. tar gz repository in AFS

We are using this convention to name the tar.gz file: <repo_name>_moved_to_github_see_readme.tar.gz. See this example:

$ ls /afs/slac/g/cd/swe/git/repos/package/timing/
bsa_moved_to_github_see_readme.tar.gz  bsssBldDriver.git  hpsTpr_moved_to_github_see_readme.tar.gz  jitterCleaner.git  README_github  tpg.git

Create or edit the README_github file in the repository directory in AFS. Here's what the content looks like:

$ cat /afs/slac/g/cd/swe/git/repos/package/timing/README_github 
The modules below were transferred to GitHub. eco already knows it, so
if you use eco -m you will get the clone from GitHub.

The tar.gz here contains the bare repo and is just for backup purposes.

hpsTpr: https://github.com/slaclab/hpsTpr
bsa: https://github.com/slaclab/timing_bsa

8. Modify eco_modulelist

In your local area (not the release area!), use eco to retrieve the module list:

eco -m eco_modulelist

Edit modulelist.txt on your local copy and commit your changes.

Here's a snippet of this file that can be used as an example:

# Packages (or non-epics drivers)
l2Mps                   https://github.com/slaclab/l2Mps.git
yamlReader              https://github.com/slaclab/yamlReader.git
hpsTpr                  https://github.com/slaclab/hpsTpr.git
commonATCA              https://github.com/slaclab/commonATCA.git
bsa                     https://github.com/slaclab/timing_bsa

Now push the changes and update them in the release area:

git push origin master
cd /afs/slac/g/lcls/tools/eco_modulelist
git pull

Now test with eco to see if the clone is made from GitHub and if the repository was correctly set in modulelist.txt.

9. Configure permissions for repository and branches

On the GitHub repository (web system):

• Click on Settings.
• Click on Collaborators and teams.
• Click on Add teams.
• Search for the group tid-cds-acs and make this group admin of the repository.
• This is only for code created at SLAC and not for code from the community:
  • Still in the Settings page, click on the General link on the menu on the left. 
  • Find the section Default branch. Change from main to pre-release. This is to avoid accidental clones starting at main and pull requests made at main.
  • Still in the Settings page, click on the Branches link on the menu on the left. 
  • Click on Add branch protection rule.
  • For the main branch:
    • Branch name pattern: type main in this field.
    • Check these boxes:
      • Require a pull request before merging
      • Require approvals
      • Require conversation resolution before merging
      • Lock branch
    • Click on Save changes.
  • For the pre-release branch:
    • Branch name pattern: type pre-release in this field.
    • Check these boxes:
      • Require a pull request before merging
      • Require approvals
      • Require conversation resolution before merging
    • Click on Save changes.

10. Communicate that the migration is complete

Send an e-mail to all previous developers saying that the migration is complete.