Git Workflow

What goes in a paper repository vs. the ss3sim package?

The guiding principle should be that any sharable functions that are potentially useful for other projects should be in the ss3sim package itself.

Anything specific to a particular project and not something that is likely to be used in a different project in the future should be in a project-specific folder.

Edit paper-specific code in the paper repository. Contribute code to the ss3sim package as necessary. Your paper specific code should load the ss3sim package.

Editing the package locally with Git and devtools

Assuming you don't have any local changes that you haven't synchronized and you're in the master branch, pull the latest changes from the server:

git pull

The basic idea is to always work in a branch and push those to the server where they can be merged. This avoid conflicts and lets others discuss, edit, and test your changes before integrating them.

Create and checkout a branch for your edits:

git checkout -b my-new-feature

Now edit the functions. To load your edits quickly and test, run:

devtools::load_all()

Here, and below, I've specified the prefix devtools:: to be clear where the functions come from. As long as you load the devtools package, you can skip the devtools:: part. It can be worth throwing this into your .Rprofile file so devtools is always available:

if (interactive()) {
    suppressMessages(require(devtools))
}

Alternatively, if you work in RStudio, all of these devtools functions are available from the "Build" menu and via keyboard shortcuts. (Also Git is built in.) The built in devtools functions alone can make it worth doing package development work in RStudio. Files should autoupdate, so you can always edit in your editor of choice and document, build, and test in RStudio.

Back to development...

If you updated any documentation, run:

devtools::document()

If you want to do a full install (say to check the vignette or documentation or to make the revised package available through library(ss3sim)), run:

devtools::install()

When you're happy with your changes, run:

devtools::check(cran = TRUE)

If things are broken, fix them.

Assuming everything looks good, commit and push your changes to the server:

git add <your files>
git commit -m "My changes"
git push origin my-new-feature

If you were working on an existing branch and there's any chance someone else might have pushed changes to the branch you're pushing to while you were editing (you can check on GitHub), then, before you push your changes, run:

git fetch
git rebase
git push origin my-new-feature

This will rewind the code, apply the other person's changes, and then apply yours on top before pushing to the server. This makes for a nice clean commit history.

Now, go to the GitHub ss3sim site, find your branch, and click the green button "Compare and pull request".

Add a message summarizing your changes, if possible.

Then click the green button "Send pull request".

Now, to get back to the master branch, if you want:

git checkout master

And to get back to your branch:

git checkout my-new-feature

You can continue adding, committing, and pushing new changes on your branch before your branch gets merged.

Reading

The "Package development" section at: http://adv-r.had.co.nz

https://support.rstudio.com/hc/en-us/articles/200486508-Building-Testing-and-Distributing-Packages