Skip to content

Workflow for Contributors

Jump to bottom
Nadia Dencheva edited this page Aug 31, 2023 · 4 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.

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

Example Workflow

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

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

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

First, always fetch the upstream branch to get the latest changes.

git fetch upstream

Make a new branch called feature1 off upstream/main.

git checkout -b feature1 upstream/main

You will see a message like the following:

Branch feature1 set to track upstream/main

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 romanca package in "editable" mode with the test dependencies:

 install -e .[test]

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

git fetch upstream
git rebase upstream/main

It is better to use rebase than merge as the commit log of upstream/main 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>/romancal.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 upstream/main by clicking on Create pull request button. This will take you to the main Romancal 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.

Setting up a developer environment

  • Create a new environment

  • cd into the romancal repository working directory

  • Install developer dependencies using the requirements-dev-st file

    cd romancal pip install -r requirements-dev-st.txt

  • install romancal and test packages in this environment

    pip install .[test]

Clone this wiki locally