Workflow for vignettes

[friendly]

Yesterday, I made a pull request for my vignettes branch that I created in my repo. By mistake, I merged it into master. It didn't do any harm, because it just created a vignettes/ directory with a dummy file.

Going forward, especially if there will be others working on vignettes, we need some instructions for how this should work. In the repo for my datavis site, https://github.com/friendly/datavis, we have the following:

Workflow for development

• git checkout master
• git pull
• git branch {new-development-branch-name}
• git checkout {new-development-branch-name}
• ...git add and git commit code to the new branch
• ...develop, test, develop, test
• git push -u origin {new-development-branch-name}
• ...once the development is finished, create a pull request for the branch to be merged into master.

[These should probably be described in RStudio-friendly terms, rather than just git commands.]

Questions:

• How should we modify these here?
• Should everyone involved have their own vignettes branch in their local repo?
• Should we bring the develop branch up to date, and merge there?

[friendly]

To get started, I pulled from Lahman in RStudio. It didn't show the vignettes branch on the pull-down list. I found I had to use the shell and issue the following command:

$ git checkout -b vignettes --track origin/vignettes
Branch vignettes set up to track remote branch vignettes from origin.
Switched to a new branch 'vignettes'

Then it showed up in the RStudio list.

[philchalmers]

I'm going on the assumption here that those who are going to contribute vignettes have little to no working knowledge of git. The best recommendation I can give, with the least amount of steps, would be:

1) Fork the repo on Github to make their own public version. 2) git clone path/to/their/Lahman.git or RStudio's "Create a new project via Git" 3) Make edits to their local master branch. commit, push, pull, the usual git-flow 4) When they're ready, send a pull request from their Github repo to the original master branch located here.

Minimal working parts, and keeps all branches focused on master to avoid a working knowledge of how branches work. When/if their forked version goes out of sync with the main repo it will not be an issue at merge time so long as they only work on files in vignette/. For even fewer conflicts, tell everyone to pick a unique name for their .Rmd files so that there will never be conflicts.

[friendly]

That seems simple and sensible. There is a nice diagram showing these steps at https://github.com/jennybc/happy-git-with-r/blob/master/img/git-fork-new-project-push-pull-request.png

[MonkmanMH]

I have been using the latest version of RStudio, which (through the "project" functionality) allows you to push and pull your commits directly to github. More info here: https://support.rstudio.com/hc/en-us/articles/200532077-Version-Control-with-Git-and-SVN

I have my own fork of cdalzell/Lahman, and have been working within the vignette branch of that fork.

I've just submitted a pull request to the main repo--I'm not sure if anyone else wants to review what I have done before hitting the merge button...

I do see that the are some stylistic differences between my vignette and @friendly's that we need to harmonize. It will require a bit of finicky copy editing, so I'm happy to follow your lead on this.

[friendly]

I see your vignette at https://github.com/MonkmanMH/Lahman/blob/vignettes/vignettes/run-scoring-trends.Rmd I don't see any problem with it, except for some possibly spurious subsection headers like:

### Sub-titles and captions with ggplot2