How do I make a pull request on GitHub

[caro401]

Article type

This is a concrete article (how do I...)

The title should be something like: How do I make a pull request on GitHub

Target audience

Someone who knows just enough about git (see #2) to make commits and stuff, and knows what GitHub is (#4 ). Nothing specific about code.

The target user is trying to contribute to some repository they don't own in a small way. Take the example of fixing a typo in some docs? (the idea that this article is required came up while helping historians contribute to some markdown documentation)

Things to cover

• what even is a pull request? (don't think this is enough to need a whole separate article?) Note this is a hosting platform thing, not a core git thing

• the steps are the same on most other code hosting platforms, just the UI might look a bit different. GitLab calls these things Merge Requests, but it's the same concept.

• this process is very dependent on what maintainers want for their project! Read their docs/readme/contributing guide first, and do what they say not what we do!

• in the absence of conflicting requests from the maintainers of the thing you want to contribute, here's a process I like:

• code on a team you're part of (don't need to fork)

  • tell people you're gonna do the thing!
  • clone code
  • take branch
  • make change
  • make commit (with a good message!)
  • push your branch
  • make sure builds are green etc
  • open a PR
  • get feedback
  • do more commits
  • get approved
  • merge PR
  • success!

• code not on your team (Do need to fork)

  • fork the repo
  • do the rest of the things (don't forget to branch!)

• how to write a good PR description (and good commit messages along the way)

• general tips like don't make your PR too big, ask the relevant person for review

• what's builds and why do i care if they are green (very vaguely, just enough to say that the build things are there for a reason, and you should make them green, ideally before making PR)

Is it related to anything else we've written about?

Articles #4 (published) and #2

Anything else?

There's a blog post somewhere explaining why not to ask to merge from main on your fork, I'll find it

https://intro.opensauced.pizza/#/ is a good resource if people want to do more open source stuff, but not from an academic perspective

Next steps

Would you prefer:

I want to write the article mostly myself

@danwaterfield did I forget anything in the outline?