Inclusion of branch structure, issue collection and similar?

[jsonbecker]

Should this presentation include addressing:

• [x] common workflows with branches (gitflow, githubflow, environment-based branching, etc)
• [x] issue collection/management
• [x] commit message templates
• [x] PR templates
• [ ] CI for testing

[wbuchanan]

@jsonbecker I think providing some examples would definitely be a good idea. I've tried to respond to things in order below:

• I think adding something about GitHub Flow would definitely be useful and helpful in terms of selling the use case for vcs in general.
• This could be pretty interesting to tackle. Some of the folks from @MapBox did a Strata conference talk about how they basically abandoned email in favor of communicating nearly exclusively through issues; definitely a lot of fertile ground here.
• Do you use commit message templates at your shop? I know Microsoft has some standards about commit messages that they use, but I've never really given much thought to the templates myself.
• PR templates would probably be good to address. I'm fairly sloppy with that stuff, but if you already have examples pulled together that would probably be pretty useful.
• The CI part I'm not too sure about only because everyone might not be working in a language that lends itself to a CI tool natively (e.g., Stata, etc...) and some languages don't seem to have good ways to operationalize tests (e.g., SQL). It might be good to provide an overview, but I don't know how far in depth things should go. On that note, it might be good to talk about PR standards (e.g., can only push code if it includes a test, etc...).

[jsonbecker]

We use commit templates and PR templates.

Commit templates are pretty straightforward for us:

1. Message should state what was done in an active verb.
2. Header for Why you did an action with bullets.
3. Header for How you did something with bullets.

Filters out schools with fewer than 10 students

## Why
* N size rule restrictions

## How
* Used filter(n < 10) after group_by when preparing "agg_data"

[jsonbecker]

For a PR we use:

#### What does this PR do?
*

#### Where should the reviewers start?
1.

#### How should this be manually tested?
1. 

#### Any background context you want to provide?
*

#### What are the relevant tickets?
* 

#### Screenshots?
![Image of Yaktocat](https://octodex.github.com/images/yaktocat.png)

#### Questions:
*

[wbuchanan]

@jsonbecker that seems like it would be pretty helpful to get people using the tool in a more consistent way and to provide consistent information to act on. Does your team use any formal code review practices or tools?

[jsonbecker]

We require two reviews to close a PR in addition to passing the CI checks.

[wbuchanan]

@jsonbecker That works. Do you have any standard formatting for review comments as well? I would guess the more upfront structure we can provide the better since it will make it easier for others to get up and running with more structure.

[wbuchanan]

@jsonbecker I think we can make the commit and pull request templates part of the conventions for the repository, unless there is any strong objection from @nathant23 or @daphnejenkins. I just updated the session proposal to fix some of the formatting and used the commit template you suggested and it seems pretty logical to me.

[wbuchanan]

@jsonbecker Do you know of any more convenient ways to use the template if you're working from the command line? It can get kind of ugly looking to use the same type of template:

git commit -m "Updated project README with a bit more info" -m "## Why" -m "* Direct interested parties to the repository wiki" -m "## How" -m "* Added new subsection to the README that included the link to the wiki."

Not sure if it would parse \n as a newline character or not, but thought you might know of a cleaner way of using the template. Also, since some users are more likely to rely on a GUI, do you know if there is a way of configuring any of the clients to present a predefined template for commit messages and PRs?

[jsonbecker]

For PR templates you put a text/markdown file in .github/ in the repo named PULL_REQUEST_TEMPLATE.

For commit messages there's probably a way to do it in gitconfig but I made a file called ~/.gitmessage and ran this command:

git config --global commit.template ~/.gitmessage

Then you have to use git commit or git commit -v. You can't use the template with -m, which is made for quick and dirty messages.

Sent from my iPad

On Apr 9, 2017, at 8:09 AM, William Buchanan notifications@github.com wrote:

@jsonbecker Do you know of any more convenient ways to use the template if you're working from the command line? It can get kind of ugly looking to use the same type of template:

git commit -m "Updated project README with a bit more info" -m "## Why" -m " Direct interested parties to the repository wiki" -m "## How" -m " Added new subsection to the README that included the link to the wiki." Not sure if it would parse \n as a newline character or not, but thought you might know of a cleaner way of using the template. Also, since some users are more likely to rely on a GUI, do you know if there is a way of configuring any of the clients to present a predefined template for commit messages and PRs?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[wbuchanan]

@jsonbecker It adds

[commit]
    template = /Users/billy/.gitmesage

to the .gitconfig file when I did that. I assume there's a similar way of modifying the config file to include the PR template as well.

[jknowles]

Hi I've been lurking but I have a couple good resources for code review that might be valuable to point toward:

https://ropensci.org/blog/blog/2016/03/28/software-review

https://github.com/ropensci/onboarding/blob/master/reviewing_guide.md

These are used to review R packages by the ROpenSci team, and they have had a lot of success with this procedure. These guidelines could be helpful for an internal team wanting to create a Git workflow too.

[wbuchanan]

@jknowles I'll definitely take a look into the code review resources. Personally I think it becomes a good way to grow institutional knowledge when the staffing model makes things like pair coding prohibitive.

[jknowles]

It has the benefit of creating a reviewable document of design decisions as well, which can be helpful for projects infrequently revisited or in cases of staff turnover.