---
# System prepended metadata

title: 'how to open a pull request, according to spondrak'
tags: [posts]

---

---
title: "how to open a pull request, according to spondrak"
date: 2021-04-24T16:55:16-07:00
description: ""
tags: posts
---

s: okay so we both have high standards.
if someone were to open a pull request (PR) against say,
an open source repo one of us maintains,
what would we recommend they do?
what would we advise them to avoid?

s: what's involved in opening a PR?

- git(hub) mechanics
    - forking a repo
    - committing changes
    - pushing your changes
    - opening a pull request
- being a Good Citizen
    - boyscout rule
    - does the project have instructions? CONTRIBUTING.md or similar
    - identifying and adhering to tacit code-isms
    - words words words
    - scope <-- this could be a whole post in itself, shit.
- quality
    - run tests
    - write new tests
    - sanity-check your change
    - unbreak the build
    - proofread

let's break down each of these.

## git(hub) mechanics

while we don't expect every new contributor to be an expert,
it helps to know version control tooling and repository hosting norms 
when you're joining a project.

### forking a repo

thankfully, this step is well-documented.
[github docs]

### committing changes

this is more than just

```shell
git add .
git commit -m "fix"
```

## being a Good Citizen

### follow the "boyscout rule"

the "boyscout rule", sometimes referred to the "camping rule",
says to leave a place better than you found it.
when you're out camping, it means to pick up litter
even if it was left out by previous campers.

in software, that means to do small bits of cleanup
within the scope of your change.
so if you're editing a conditional, fix the spacing around the conditions.
if you're editing a comment, fix the spelling on that line.

```diff
example here
```



### read contribution guidelines



### notice and follow code style norms for the project

most project owners won't document all of these in `CONTRIBUTING.md`,
and many won't even notice that they're there--kind of line an accent.


### ~~words words~~ words

this can be contentious. more words aren't always better.
in general, though, lean toward making things explicit.


### scope

this is probably the hardest to learn.

