Skip to content

Git and GitHub workflow for contibuting

Jump to bottom
Lauren Chambers edited this page Jun 26, 2018 · 8 revisions

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

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 master 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:

  1. Create a personal fork of the mirage 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 (e.g. git clone [email protected]:username/mirage.git, found by clicking the green "clone or download" button.). Note that, unless you explicitly delete your clone of the fork, this only has to be done once.

  3. cd into your newly cloned repo, and ensure that the personal fork is pointing to the upstream spacetelescope/mirage repository with: git remote add upstream [email protected]:spacetelescope/mirage.git. Note that this only has to be done once.

  4. Create a 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-ingest-algorithm) and not too generic (e.g. bug-fix). 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> - stage updated files
      3. git commit -m 'Explanation of changes you've done with these files'

  5. Push the branch to the personal fork of the GitHub repository - 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/mirage GitHub repository, create a pull request - there is a button for that on your fork's page. You will want to set the base fork pointing to spacetelescope:master 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'.

  7. Assign the pull request a reviewer, selecting a member of the mirage team. 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 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>.

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

    1. git checkout master
    2. git fetch upstream master
    3. git rebase upstream/master
Clone this wiki locally