Contributing

My background's wikipedia, I really support flexible collaboration between strangers.

I aim to be the most-welcoming, and least-pedantic maintainer I can be.

Software is daunting enough.

Contributing on github should be a light, easy, non-scary thing to do.

1) Got an idea? - Click the fork button:

that copies the project to your personal github, where you can make whatever changes you want.

2) Download it onto your computer:

Github calls this a clone, I'm not sure why.

get your link from this button:

you'll need to have git, and maybe some github tokens setup but now you're able to see it on your computer

3) Get it running:

ideally this is very simple.

this will download the random things your computer needs to run (you'll need npm installed - but that's pretty easy) this actually works pretty well usually.

4) Run the tests:

you don't have to do this, but sometimes it's nice to see the green dots:

😎

5) Goof-around:

you can change things, and run it again.

try npm run start or npm run watch.
(People tuck these commands inside of the ./package.json file.)

git status shows the changes you've made git diff shows it in more detail

6) Commit your changes:

add edits to your repo with a commit (not as scary as it sounds!)

git add any changed files git commit - add a small message git push - upload it to github

- try not to add things you didn't mean to here. -

(It's a pain to un-commit things)

7) Make a pull request:

kindly offer to put your changes back into the main codebase:

github does a pretty-good job at this. say hello! explain your changes a little bit.

If it's a big change, or you're going to be adding new features, you may want to open an issue to chat about it first.

• sometimes there are concerns, or discussions to have.
• sometimes maintainers have automatic tests that run during a pull request.
• some maintainers ignore good Pull Requests, which is rude. (It sometimes happens!)
• maintainers have a hard job.

don't let that bother you.

---

Helpful advice

• best to ensure the tests are still passing, after you've made your changes

• Bonus points for adding more tests, for the new stuff you're adding.

• to change your PR, you can simply do another commit+push, it appears automatically.

• try to keep your Pull Request small, so it's easy to review.

• sometimes your editor will automatically format things, which can mess-up a clean PR.

• no-need to commit new builds, or increment version numbers. Let maintainers do that.

• it may take some time before your change enters a new release. Don't sweat.

---

🕐 Staying up-to-date:

your fork will become stale, when the main codebase changes

you may see this:

you have to do this yourself. It's not totally straightforward.
Everyone forgets to do this.

you can do this through the compare button on github, though personally I've found this a bit confusing.

I prefer to do this stuff, from Cristina Solana:

git remote add upstream git://github.com/REPO_ORG/REPO_NAME.git
git fetch upstream
git pull upstream master
git push

then you'll see this:

I put this as a bash-alias, so I don't have to think about it anymore.

This ensures your next PR won't have any gross merge conflicts.

Good work! 🏆

After a few times, this stuff gets easier, I promise.

It used to be so much harder.

git, github, homebrew, and nodejs have really lowered the barrier to software projects. A lot of tools, and help are available