Skip to content

Development Workflow

Jump to bottom
rpruim edited this page Jan 27, 2012 · 33 revisions

This is an outline of the workflow for development and maintenance of the mosaic package.

Dependencies

Maintainers will need the following available to follow this workflow completely.

  • scripting languages: R, bash, perl,
  • R packages for development: devtools, testthat, optparse, roxygen2
  • R packages for the package itself: lattice, grid, methods, Hmisc, utils, MASS, reshape2, [manipulate]
  • R packages to compile ancillary materials (e.g. books): knitr

Currently, it is assumed that all scripts are run from the parent directory of bin. For example, ./bin/doitall

Github workflow

This outline is still in progress. The git/github workflow is based primarily on the "Private Small Team" model from the ProGit document with a bit of "Private Managed Team" influence.

Creating new functionality

  1. Create an issue at github describing the new feature to be added and assign the issue to the person doing the coding.

  2. Make sure what you have locally is up to date

git fetch    # safer than git pull in that it allows/requires you to do the merging manually

or

git pull     # this will do any necessary merging that can happen without your intervention

  1. Create a branch named after the issue number (e.g., issue001). Pad to 3 digits.

    Typically this branch will come off of the beta branch or one of its sub-branches. Do not work directly in master or beta.

git branch issue001 origin/beta   # create the new topic branch based on origin/master
git checkout issue001             # switch to the new branch (can also be done inside RStudio)

The last two commands can be combined into

git checkout -b issue001 origin/beta
At this point, **the new topic branch is only on your local machine**. 

(You could build and checkout the new branch using

git checkout -b issue001 beta

but this links your new work to other work you have done since your local beta was in sync with origin/beta. Sometimes this might be just what you want. But if you can work from origin/beta, that is probably the better way to go -- especially if you abandon work currently in the local beta but not in origin/beta.)

  1. Create, document, and test code, committing frequently as you work.
git commit              # or click on commit button in RStudio
# do some stuff
bin/checkpackage.sh     # check that everything is still OK
git commit              # or click on commit button in RStudio
  • Whenever possible, new code should result in new examples, new unit tests, or both.
  • use bin/checkpackage.sh to make sure documentation is up to snuff, examples work, tests pass.
  • First line of commit message should be a short description of committed work. Second line should be blank. The next few lines can add additional details.
  • Avoid committing too many things all at once. Commits are cheap.
  • It is possible to get back to the state you were in at any commit.
  1. Need consultation? Push your topic branch so the rest of us can see it.
git checkout issue001   # or select branch in RStudio
git commit              # or select commit in RStudio
git branch -a           # list all the branches to make sure that there isn't already an origin/issue001 
git push -u origin issue001  # -u will set things up so local issue001 track origin/issue001 and push/pull work
git will report back that the new branch has been made and tracking established. Now others can inspect origin/issue001 or use git pull to pull the branch to their local machine and work with you to fix problems.  Or they can grab a local copy with

git checkout --track origin/issue001

  1. merge topic branch into beta

    When you are to the point where the code in your topic branch is ready to be included in the beta branch,

git checkout beta
git pull                 # or click pull in RStudio (or git fetch plus git merge)
git merge issue001       # incorporate new stuff into local beta
bin/checkpackage.sh      # make sure everything is still good

  1. merge local beta into origin/beta

    Since we set up the local beta branch to track origin/beta, this can be done with

git checkout beta        # or select the beta track in RStudio
git push                 # or click push in RStudio

  1. When ready for public release, beta can be merged into master.

  2. Prior to merging beta into master, it may be useful to have an alpha branch that will become the next beta so that we can continue working on new stuff without delaying the release of more mature code. If we create an alpha branch, it will work just like the beta branch.

Fixing a bug, updating documentation, etc.

But fixes are similar except that those for which immediate deployment is desired could be done in master rather than beta. In brief:

git checkout master
git checkout -b issue002
git commit
git checkout master
git merge issue002
git push

CRAN submission

When master is rebuilt, the resulting package should have a new R version number and be submitted to CRAN.

Building and Checking the Package

origin/beta and especially origin/master should ideally always compile cleanly. Use our scripts to check for this. If you write code to create interactive tools, install the package and test them out. Don't merge in topic branches until everything checks out.

When inevitable bugs are discovered, they should be fixed as quickly as possible.

Clone this wiki locally