Git software development workflow¶
This document describes the development workflow for OSG software packages kept in GitHub. It is intended for people who wish to contribute to OSG software.
Git and GitHub basics¶
If you are unfamiliar with Git and GitHub, the GitHub website has a good series of tutorials at https://docs.github.com/en/get-started
Getting shell access to GitHub¶
There are multiple ways of authenticating to GitHub from the shell. This section will cover using SSH keys. This is no longer the method recommended by GitHub, but is easier to set up for someone with existing SSH experience.
The instructions here are derived from GitHub's own instructions on using SSH keys.
Creating a new SSH key (optional but recommended)¶
If you already have an SSH keypair in your
~/.ssh directory that you want to use for GitHub, you may skip this step. It is more secure, however, to create a new keypair specifically for use with GitHub.
The instructions below will create an SSH public/private key pair with the private key stored in
~/.ssh/id_github and public key stored in
Generating the key¶
ssh-keygen to generate the SSH keypair. For
<EMAIL_ADDRESS>, use the email address associated with your GitHub account.
[[email protected] ~ ] $ ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_github -C <EMAIL_ADDRESS>
Configuring SSH to use the key for GitHub¶
Make sure SSH uses the new key by default to access GitHub. Create or edit
~/.ssh/config and append the following lines:
Host github.com IdentityFile <YOUR_HOME_DIR>/.ssh/id_github
Adding the SSH public key to GitHub¶
Using the GitHub web interface:
- On the upper right of the screen, click on your profile picture
- In the menu that pops up, click "Settings"
- On the left-hand sidebar, click "SSH and GPG keys"
- In the top right of the "SSH keys" box, click "New SSH key"
- In the "Title" field of the dialog that pops up, enter a descriptive name for the key
- Open the public key file (e.g.
~/.ssh/id_github.pub(don't forget the
.pub)) in a text editor and copy its full contents to the clipboard
- In the "Key" field, paste the public key
- Below the "Key" field, click "Add SSH key"
You should see your new key in the "SSH keys" list.
Testing that shell access works¶
To verify you can authenticate to GitHub using SSH, SSH to
[email protected]. You should see a message that 'you've successfully authenticated, but GitHub does not provide shell access.'
We use the standard GitHub pull request workflow for making contributions to OSG software.
If you've never contributed to this project on GitHub before, do the following steps first:
- Using the GitHub web interface, fork the repo you wish to contribute to.
Make a clone of your forked repo on your local machine.
<USERNAME>is your github username and
<PROJECT>is the name of the project you want to contribute to, e.g. in order to clone my local fork of the
[[email protected] ~ ] $ git clone https://github.com/ddavila0/technology.git
If you get a "Permission denied" error, your public key may not be set up with GitHub -- please see the "Getting shell access to GitHub" section above.
If you get some other error, the GitHub page on SSH may contain useful information on troubleshooting.
Once you have your local repo, do the following:
Create a branch to hold changes that are related to the issue you are working on. Give the
<BRANCH>a name that will remind you of its purpose, including any relevant ticket numbers, such as
[[email protected] ~ ] $ git checkout -b <BRANCH>
Make your commits to this branch, then push the branch to your repo on GitHub.
[[email protected] ~ ] $ git push origin <BRANCH>
The Art of Good Commits
In addition to writing good code, it's important to organize your changes that are helpful to those viewing them in the future (including yourself!). This includes:
- Splitting up changes into logically separate chunks (
git rebasecan be a helpful tool for this)
- Describing the "why" of the change in addition to the "what" and "how" (utilizing the commit body if necessary)
- Writing succint commit message titles in the imperative (limited to 72 chars)
- Including any relevant ticket numbers (e.g.,
Change that default path (SOFTWARE-2345)).
See online guides such as this one for more details.
- Splitting up changes into logically separate chunks (
Select your branch in the GitHub web interface, then create a "pull request" against the original repo. Add a good description of your change into the message for the pull request. Enter a JIRA ticket number in the message to automatically link the pull request to the JIRA ticket.
Request a review from the drop down menu on the right and wait for your pull request to be reviewed by a software team member.
- If the team member accepts your changes, they will merge your pull request, and your changes will be incorporated upstream. You may then delete the branch you created your pull request from.
- If your changes are rejected, then you may make additional changes to the branch that your pull request is for. Once you push the changes from your local repo to your GitHub repo, they will automatically be added to the pull request.
This section is intended for OSG Software team members or the primary developers of a software project (i.e. those that make releases). Some of the steps require direct write access the GitHub repo for the project owned by
opensciencegrid. (If you can approve pull requests, you have write access).
A release of a software is created from your local clone of a software project. Before you release, you need to make sure your local clone is in sync with the GitHub repo owned by
opensciencegrid (the OSG repo):
If you haven't already, add the OSG repo as a "remote" to your repo:
<PROJECT>is the name of the project you are going to release, e.g.
openscience/technologyrepository it would be
Fetch changes from the OSG repo:
[[email protected] ~ ] $ git fetch upstream
Compare your branch you are releasing from (probably
master) to its copy in the OSG repo:
[[email protected] ~ ] $ git checkout master; git diff upstream/master
There should be no differences.
Once this is done, release the software as you usually do. This process varies from one project to another, but often it involves running
make upstreamor similar. Check your project's
READMEfile for instructions.
- Test your software.
Tag the commit that you made the release from. Git release tags are conventionally called
VERSION, where VERSION is the version of the software you are releasing. So if you're releasing version 1.3.0, you would create the
Once a tag has been pushed to the OSG repo, it should not be changed. Be sure the commit you want to tag is the final one you made the release from.