git & GitHub workflow for contributing

The best method for contributing software to the jwql project is a workflow that involves forking the jwql repository, developing changes on "feature" branches, and opening pull requests through GitHub.

Note that the jwql team employs a release-driven git workflow, as shown in the following diagram:

As such, all feature branches should be branched off of and merged back into the develop branch.

Contributing new features or bug fixes

The first question you will have to figure out is whether you should open an issue for this update - if you think that this change will be solving a significant problem or add a significant enhancement to the project then it would be advantageous to open an issue ticket here. This will allow both individuals and the team as a whole to keep track of the project and our progress as we go. Any appropriate individuals should be assigned to the issue, and a label(s) should be tagged.

Following that, any changes that you want to eventually make to the main or develop branch should be done through the workflow where you create a fork and work on your own branch before submitting those changes to be reviewed through a pull request. Instructions on how to do those things can be found below. Note that these instructions are for interacting with git through the command line, however, there are alternatives with graphical user interfaces such as sourcetree.

1. Create a personal fork of the jwql repository by visiting the spacetelescope repository and clicking the Fork button. Note that this only has to be done once.

2. Make a local copy of your personal fork by cloning the repository, using the URL found by clicking the green "clone or download" button. Either use HTTP or SSH with one of the following commands:

   • with HTTP: git clone https://github.com/<username>/jwql.git
   • with SSH: git clone [email protected]:<username>/jwql.git

   Note that, unless you explicitly delete your clone of the fork, this only has to be done once.

3. Ensure that the personal fork is pointing to the upstream spacetelescope/jwql repository:

   • with HTTP: git remote add upstream https://github.com/spacetelescope/jwql.git
   • with SSH: git remote add upstream [email protected]:spacetelescope/jwql.git

   Note that this only has to be done once.

4. Create a "feature" branch off of the develop branch on the cloned personal fork to develop software changes on. Branch names should be short but descriptive (e.g. new-database-table or fix-dark-monitor) and not too generic (e.g. bug-fix, updates). Also consistent use of hyphens is encouraged.

   1. git branch <branchname> - you only need to do this when you first create your branch.
   2. git checkout <branchname> - you can use this command to switch back and forth between existing branches.
   3. Perform local software changes using the nominal git add/git commit -m cycle.
      1. git status - allows you to see which files have changed.
      2. git add <new or changed files you want to commit>
      3. git commit -m 'Explanation of changes you've done with these files'

   ⚠️ ⚠️ ⚠️

   Please do not develop software changes on your fork's develop branch. Be sure to follow step 4 to create a new "feature" branch, so that you can pull updates from spacetelescope/develop into your own origin/develop without messing up your feature branch changes.

   ⚠️ ⚠️ ⚠️

5. Push the feature branch to the GitHub repository for the personal fork - this will deliver all committed changes to the branch version on the web which makes it accessible to other team members. The following are the commands to do this:

   1. git push origin <branchname> for your first push, or
   2. git push <branchname> will also work after the first push of your branch.

6. On the spacetelescope jwql GitHub repository, create a pull request - there is a button for that on the previous linked page. You will want to set the base fork pointing to spacetelescope:develop and the head fork pointing to the branch on your personal fork (i.e. username:branchname). Note that if the branch is still under heavy development, you can put WIP: at the beginning of the pull request title to signify that the pull request is still a work in progress (i.e. WIP: Example Pull Request Title). Not until the WIP: tag is explicitly removed will the pull request be deemed 'mergable'. Be sure to follow the JWQL checklist for contributors of pull requests.

7. Assign the pull request a reviewer, selecting one or several member of the jwql team (preferably at least @bourque or @laurenmarietta). They will review your pull request and either accept the request and merge, or ask for additional changes.

8. Iterate with your reviewer(s) on additional changes if necessary. This will involve addressing any comments on your pull request which can be found on this webpage. You may end up iterating over steps 4.ii, 4.iii and 5.ii several times while working with your reviewer - do not despair.

9. Once the pull request has been accepted and merged, you can delete your local branch with git branch -d <branchname>.

Making hotfixes

As shown in the diagram above, sometimes hotfixes need to be made directly to main. The nominal workflow for such a scenario is as follows:

1. Assuming steps (1) through (3) in the previous section are completed, create a new branch named hotfix-<description> off of main, and commit any necessary changes following the workflow described in step (4) in the previous section.

2. Push the hotfix branch to your personal fork, and open two pull requests for that branch: one that merges the branch into spacetelescope:main and one that merges the branch into spacetelescope:develop.

3. For each of these pull requests, proceed with the nominal review & merge process as described in steps (7) through (9) in the previous section.

Keeping your fork updated

If you wish to, you can keep a personal fork up-to-date with the spacetelescope/jwql fork by fetching and rebasing with the upstream remote:

1. git checkout develop
2. git fetch upstream develop
3. git rebase upstream/develop

Collaborating on someone else's fork

Users can contribute to another user's personal fork by adding a remote that points to their fork and using the nominal forking workflow, e.g.:

1. git remote add <username> <remote URL>
2. git fetch <username>
3. git checkout -b <branchname> <username>/<branchname>
4. Make some changes (i.e. add/commit cycle)
5. git push <username> <branchname>