Thanks to Hugo and Bruce that started guides that I've used to combine into this one.


  • Adjusting the environment with the needed variables

# Environment variables for the new EPICS Base
source $EPICS_SETUP/epicsenv-7.0.3.1-1.0.bash
source /afs/slac/g/lcls/tools/script/release/eco_tools/latest/add-to-env.sh


  • If you don't have a local repository yet

Make sure that you don't have a local repo, yet. Just run this command for new modules not available in AFS. This will create a new local Git bare repository in $GIT_ROOT/package/epics/modules/.

git-bare-repo $GIT_ROOT/package/epics/modules/<module_name>.git


  • Clone the external GitHub repo into your sandbox
git clone <URL> <local_directory>
cd <local_directory>


  • Stitch the external module with SLAC's internal AFS repo

The branch names and remote names below are only suggestions. They will only be available in your local repo and visible only to you.

The script epics-release needs a remote with a name containing the string "origin". So, the remote in AFS needs to have it if you want to use epics-release.

At the same time, avoid using the string "origin" in the names of other remotes as the script epics-release uses it to define the remote repo. So, for instance, if you have 3 remotes and call them abc-origin, origin-123, and Myorigin, epics-release will choose randomly among them to decide which remote to use.

Following the suggestions below you will have 2 remotes:

  1. github: tied to the community GitHub repository.
  2. afs-origin: tied to the AFS local repository.
git remote rename origin github
git fetch github --tags 

# Check the default name of 
# the main branch in GitHub, that will 
# probably be "master" or "main".
git checkout github/master
# or
git checkout github/main

git remote add afs-origin <afs_directory>

If you had to create a bare repo as described above, let's create a SLAC branch:

git co -b slac-trunk
git push afs-origin slac-trunk

And now redefine the HEAD symbolic link:

pushd $GIT_ROOT/package/epics/modules/<module_name>.git
git symbolic-ref HEAD refs/heads/slac-trunk
popd

If working with a previously created AFS repo, you need to verify what is the name of the main branch in the AFS. I'll call it <main_afs_branch>.

git fetch afs-origin
git checkout <main_afs_branch>
git rebase -i <main_github_branch_name>
  •  Create the branch that will be based on a tag from the community

We have a naming convention to derive a branch from an external tag. The guideline is here: Git Workflow for EPICS module development, section "Typical Git workflow for EPICS Collaboration modules". Look at the desired tag from the community. Usually, you are going to get the most recent one. Let's call the chosen tag <tag_number> and create a local branch based on the tag number:

git checkout <tag_number>

git checkout -b <tag_number>-0.branch
git push afs-origin <tag_number>-0.branch


Now it is time to change a few things in the module from the community as it can build in our environment and follow our conventions:

  • Modify the module to build for git workflow.
  1. Compare the .gitignore from the community with $TOOLS/script/eco_tools/gitignore.template and manually merge them. Check if entries in the .gitignore from the community need to be removed. For instance, "*.local" is something that will not work at SLAC and must be deleted.
  2. git add .gitignore
  3. git commit -m "Modified .gitignore"
  4. cp $TOOLS/script/eco_tools/RELEASE.local.template configure/RELEASE.local
  5. Edit configure/RELEASE.local, moving module versions and dependencies from RELEASE to RELEASE.local
  6. Update the dependent module versions in RELEASE.local to the latest release. Use epics-versions to help find the latest releases.
  7. cp $TOOLS/script/eco_tools/RELEASE.template configure/RELEASE
  8. Before building, you will need a temporary RELEASE_SITE file. Don't commit it to GIT! Use "epics-update -r" to retrieve a new RELEASE_SITE.
  9. Run make, fixing any build errors.
  10. Run "git status", and add any additional files to .gitignore as needed. Add and commit .gitignore if needed as described in 2 and 3 above.
  11. git add configure/RELEASE*
  12. git commit -m "Modified to build for git workflow"
  13. Update RELEASE_NOTES for your new release. If the file doesn't exist, copy a model from another SLAC module and fill it in appropriately.
  14. git add RELEASE_NOTES
  15. git commit -m "Updated RELEASE_NOTES"
  16. Make sure all your changes are committed. You should get a clean "git status".
  17. Tag, push, and build your release using: epics-release -r <release_number>.


  • No labels