Add simple `git` instructions to GitHub issue templates

[rebecca-shoptaw]

Describe the problem that you'd like solved

There's an ongoing background issue on OL where contributors often have trouble keeping their branches up to date, and run into merge conflicts and rebasing issues that require staff intervention. The idea we've settled on to help prevent this is to add clear and simple git instructions in a high-visibility place, i.e. at the end of the issue template. This way, contributors will be reminded to update their master branches before making a new branch for the PR, and to update their PR branch before making new changes to it.

Proposal & Constraints

Ideally, this would involve adding a git section to the issue template (perhaps above "Stakeholders") -- "Working with Git"? -- that includes:

• Suggested branch name: (optionally filled out by issue's lead)
• Instructions re: how to keep master branch updated, i.e.:

git switch master
git pull upstream master
git push origin master

• Instructions re: what to do next if starting a new branch vs. updating an old one:

git switch -c name-of-new-branch

vs.

git switch name-of-existing-branch
git rebase master

• Link to rebase section of Git Cheat Sheet for troubleshooting and more info

Additional context

Note: Just tagging everyone who was in the conversation about this, feel free to un-tag yourself if you don't want notifications. 🙂

Also, this will obviously add some length to the template and be redundant for more experienced contributors, but hopefully the benefits of reduced merge conflicts/contributor confusion would be worth it.

Stakeholders

@mekarpeles @jimchamp @scottbarnes @merwhite11

[rebecca-shoptaw]

I wrote up what I feel is a solid draft for the changes while working on the issue write-up, so I'd be happy to submit a PR with the relevant updates!

[mekarpeles]

Thank you @rebecca-shoptaw that would be great! We may want to add it to both the feature request and bug github template (but maybe not the others) for now.

[merwhite11]

Here are some additional details (aka gotchas that got me) we could add in to the template--

KEEPING YOUR MASTER & BRANCH UP TO DATE WITH UPSTREAM Repeat these steps BEFORE EACH time you start working on your branch

git switch master
git pull upstream master
git push origin master
git switch name-of-existing-branch
git rebase master

Confirm that your master and branch are up to date on your GitHub fork. If your master and/or branch are behind upstream, see Git Cheat Sheet for troubleshooting

Master

Your Branch

See Git Cheat Sheet for Troubleshooting

[rebecca-shoptaw]

@merwhite11 Amazing, thank you! We should definitely use those screenshots in the Git Cheat Sheet (plus info re: where people can find that for themselves) as a way to guide people re: how to proceed.

[tfmorris]

I recommend adding the --ff-only switch to the pull command to make sure that you're not accidentally getting merge commits on top of a commit to master in your fork. Preventing this upfront will save a lot of heartache later.

[RayBB]

@rebecca-shoptaw I know last week you were also doing quite a bit of work to update the git cheatsheet. How would you (and others) feel about adding a link to the docs in the templates instead of adding full instructions into every feature/bug report? That also gives us an opportunity to write in more detail and easily update it later (if we add to the issue template and then want to change later all the current issues will remain unchanged).

I feel moderately in favor of linking instead of in-lining these docs. Mostly because I think having docs like this in one place is easier to navigate and maintain.

[rebecca-shoptaw]

@RayBB That solution is fine by me, but I would want to run it by @mekarpeles first, as I know he was in favor of the issue template approach. Maybe a combo of putting a reminder re: staying up to date plus a link here, and putting an extra reminder/link somewhere else like the "choosing a good first issue" instructions?

[merwhite11]

@rebecca-shoptaw @RayBB I think linking to the docs in the issue template makes sense as long as it's very explicit --something like: "Follow this Git guide to create a branch and begin working on this issue."