Skip to content

Workflow

Jump to bottom
James Davies edited this page Jun 7, 2019 · 10 revisions

General Notes

All changes to the repository are made in branches on developer's fork of this repository and submitted via a pull request (PR).

Each PR should be labeled with a step label (e.g. a PR to refpix should have a label refpix) and any other relevant labels (e.g. requirement number or Trac ticket number in case we are referencing those). Each PR should be assigned a milestone (a build number or a future release version number).

A PR is merged after someone other than the submitter had looked at it. Usually this is one of the two step maintainers. If nothing else simply adding a LGTM comment should be present. Trivial changes can be merged by the submitter of the PR (use your best judgement). If the changes may affect another step consider asking that step maintainer to review them.

Travis tests will run on the repository and PRs performing as a minimum a PEP8 check. Steps which depend on other steps should have some sanity unit tests if possible as well.

Example Workflow

  • Fork the main jwst repository
  • Create a local copy of the repository you just forked and let it know where the main repository is.
git clone https://github.com/<your-user-name>/jwst.git
cd jwst
git remote add jwst https://github.com/spacetelescope/jwst.git

An Aside About GitHub Authentication

If you're cloning GitHub repositories using HTTPS, you can use a credential helper to tell Git to remember your GitHub username and password every time it talks to GitHub:

https://help.github.com/articles/caching-your-github-password-in-git/

If you clone GitHub repositories using SSH, then you authenticate using SSH keys instead of a username and password:

https://help.github.com/articles/generating-an-ssh-key/

Back to the Workflow

You should be able to look at all remotes now and see something like 

% git remote -v
jwst   https://github.com/spacetelescope/jwst.git (fetch)
jwst   https://github.com/spacetelescope/jwst.git (push)
origin     https://github.com/<your-user-name>/jwst.git (fetch)
origin     https://github.com/<your-user-name>/jwst.git (push)

The above operations are normally performed once. Now start work on a new feature/change by making a separate branch which tracks jwst/master.

First, always update the jwst/master branch to get the latest changes. 

git fetch jwst master

Make a new branch called feature1 off jwst/master.

git checkout -b feature1 jwst/master

You will see a message like the following:

Branch feature1 set to track jwst/master

Work on this branch until the new feature is ready. Then commit the changes:

git add file_names_to_commmit
git commit -m "Adding feature 1" file_names_to_commit

It's not a bad idea to test that the changes actually work. It's easiest to do this by installing the jwst package in develop mode:

python setup.py develop

Sometimes development of a new feature takes a while, and perhaps jwst/master has passed you by, or you need a bug fix in your feature branch that someone else committed to jwst/master. So to update your branch with the latest from jwst/master:

git fetch jwst master
git rebase jwst/master

It is better to use rebase than merge as the commit log of jwst/master remains cleaner once your branch is merged back in.

When all changes are made, push to your forked repository (note: you are pushing the new branch to your own forked copy of the main repository):

git push origin feature1

Now go to your forked copy (http://github.com/<your_github_username>/jwst.git) to find the branch you just pushed. (There's a link to your github account in the upper right corner of any github page. Clicking on it will take you to your github profile and you can find the repository under the tab repositories.)

If it's a new branch you will see Compare and pull tab next to the branch name.

You can look at the changes online. If everything looks good, create a PR against jwst/master by clicking on Create pull request button. This will take you to the main JWST repository on github.

  • Add relevant labels, milestones and link to issues (#issue number) and ask for a review.
  • After the review and when Travis tests pass, merge using the web interface.

PEP8

Notes on how to configure Emacs and Vim to conform to PEP8.

We use flake8 to help us maintain PEP8 standards. The flake8 codes checked are in setup.cfg in this repo. They will automatically be used with no user intervention needed. Before committing to this repo, simply run 

flake8
and it will check the same codes that get checked in our CI checks.
Clone this wiki locally