Skip to content

Feature Development Process

Jump to bottom Edit New page
Wilfred Tyler Gee edited this page Jul 27, 2020 · 4 revisions

PANOPTES Feature Development

A feature can be a code enhancement, a bug fix, or anything that changes code in the repository.

The basic approach is referred to as a triangular workflow, with 3 git repositories ("repos"):

  • upstream: This is the "official" copy of the code. Located at https://github.com/panoptes/POCS. This exists on github.
  • origin: This is your clone (fork) of the upstream repo, typically https://github.com/<YOUR_GITHUB_USERNAME>/POCS. This exists on github.
  • local: This is a clone of your origin repo, residing on your computer, where you will actually do development work.

It is called triangular because changes flow in one direction around the triangle:

  • upstream -> local: Pull (or merge) changes from the "official" PANOPTES repo into your local.
  • local -> origin: Push your local changes into your copy of the code on github.
  • origin -> upstream: Create a Pull Request (PR) to ask that your origin be merged into the official upstream.

Start work on a feature

Make sure you have followed the One Time Setup instructions below first.

By feature we mean a new capability, test, bug fix, or documentation update. Ideally the feature is kept as small as possible (i.e. one feature, not a couple of features that were convenient to develop together); it may be code that is tested but otherwise dormant because there are not yet any callers, as changing the callers is another feature.

For any feature you work on there should be a corresponding Issue. If one doesn't exist you should create one.

Please also read and adhere to the suggestions in the article In-Praise-of-Small-Pull-Requests.

Create feature development branch

For each feature, you'll want to start with the latest commit (change) on the the develop branch in the upstream repo, so make sure you have that in your repo:

git fetch upstream

Next create a branch for working on this feature... and only this feature... based on the latest commit on the upstream repo's develop. Use a descriptive name for the branch and include the Issue number at the end (nnn below).

git checkout -b name-of-feature-branch-nnn upstream/develop

NOTE: The important part here is the -b to create a new branch and the upstream/develop to have that new branch tied to the official upstream automatically.

Develop your change

Edit whatever files you need to in POCS, and run tests (cd $POCS; python setup.py test). Whenever you have code that you want to save, commit it to your local repository:

# Get a list of the files that have been changed.
git status

# Add your changed file(s) to the "staging" area for git.
git add dir-to-commit file1/to/commit file2/to/commit

# Commit those changes.
git commit

This last command will bring up an editor into which you need to add a comment describing your change. If you're just committing a small portion of your overall change, it is common to make it a very brief comment about your WIP (work in progress). For example: "wip - Test is working"

Pickup changes from upstream

Note: This only applies before you git push upstream. Don't do this once you've published your change.

While you're developing your change, other changes may be merged into upstream/develop. At appropriate times, you'll pull those changes into your feature development branch:

# Check for clean working area. Should say "nothing to commit, working directory clean".
git status

# Now pull commits from upstream "official" repo into your local repo
git fetch upstream

# Apply your changes on top of the changes made to upstream/develop.
git merge upstream/develop

# Manually merge conflicts that can't resolve and commit if necessary.
git commit

Good times to do this are when you have your code compiling and passing tests, and always immediately before you first publish (push) your feature branch to your origin repo, and from there to the upstream repo.

First push to origin

Push your local changes to your github origin:

# Make sure to use the name of the actual branch you are working on.
git push origin name-of-feature-branch-nnn

This should show you a URL that you can click on to open a new Pull Request, otherwise see below.

Create Pull Request

If you didn't click on the URL from the original push (see previous step), then open https://github.com/yourname/POCS.

GitHub should tell you that you have a recently pushed branch from which you can create a Pull Request (PR). Click the Compare & pull request button, write a description of the change. This should include the nnn identifier of the POCS Issue with a number sign in front (e.g. #1234 for issue number 1234) so that the PR will be linked to a justification for the change.

Respond to feedback and make fixes

Push Fixes

After you've made the requested changes and checked that tests are still passing, re-push your changes to your origin repo. This will automatically update your Pull Request and trigger the execution of tests.

git push

Merge upstream changes (if required)

If there are conflicts between your change and other changes that have been merged into upstream/develop (e.g. there are changes to the files that you too are changing), you'll need to merge those upstream changes into your feature branch and resolve the conflicts.

git fetch upstream

git merge upstream/develop

One time setup

Create origin repo

  1. Create an account on github if you don't already have one and log in as that user.
  2. Navigate to https://github.com/panoptes/POCS
  3. Click the fork button in the upper right of the page.

Create local repo

We assume here that you're using the git command line, and Unix like commands.

Pick a location where you'll create your clone of the POCS repo. If you are setting up a PANOPTES unit, that would be in the $PANDIR directory, probably in /var/panoptes/. Alternatively, for a development machine, you might want to create it somewhere under $HOME. For example, if you're working with multiple repos, you might use a naming scheme like:

$HOME/git/github.com/upstream-user/upstream-repo-name

If so, you'd have PANDIR=$HOME/git/github.com/panoptes. Regardless, ensure the $PANDIR directory exists or use mkdir to create it, and then cd to that directory. Next clone the POCS repo:

# **Change yourname to your github user name.** 
git clone https://github.com/yourname/POCS.git

This will create directory POCS in the current directory, download the git repo into POCS/.git, and checkout the HEAD commit of the primary branch into directory POCS. Your $POCS environment variable should point to this directory, i.e. POCS=${PANDIR}/POCS.

See Authenticating to GitHub for information about how to prove to GitHub who you are when pushing changes back to GitHub._

Set upstream repo

You'll be fetching changes made by other contributors from the upstream repo, https://github.com/panoptes/POCS, so tell git about that:

git remote add upstream https://github.com/panoptes/POCS.git
Add a custom footer
Add a custom sidebar
Clone this wiki locally