What to know before you start: 100 Pull Requests in 100 Days

It's been more than a month since I finished one of the most intense challenges of my life, and I'm still struggling to figure out the best way to write about it. I thought taking a week to reflect would help, but then life got in the way - so here I am five weeks later, still not sure how to start talking about the firehose of information and insight that I experienced in those 100 days.

I'm torn between documenting my journey vs providing advice on how to take the challenge on yourself. And I certainly don't have enough space in a single post to do either of those topics full justice.

So I thought I'd do a series of posts, starting the basic foundational concepts you need to know before starting your own 100 PRs in 100 Days challenge.

(This assumes you're relatively unfamiliar with git, GitHub, and/or Open Source Software. If you're already a wiz at all three, you most likely don't need this overview and can skip to the next post!)

Fundamentals

Open Source Software:
You've probably heard this term a fair amount, but you may not be aware that open source typically means not only that the source code is freely available, but that in many cases anyone in the world can contribute to the project, subject to approval by the project's maintainers. Different projects have different rules about contributions, ranging from very restrictive (only employees can contribute, but the source code is still available to anyone) to very broad (anyone can contribute and there are relatively few rules about what types of work totally new contributors can do.) Most fall somewhere in the middle.

git
This is popular version control software. You'll need it installed on your local development machine in order to complete this challenge. You don't need to be an expert at using it yet - this challenge help you to learn and build muscle memory! Before you do this challenge, you should make sure you do know the very basic concepts, like what a repository is, how to initiate one, how to clone one, how to make a new branch and switch among branches, and also the general process of staging and committing files. (It's OK if you're still not entirely sure WHY or WHEN you should be staging & committing changes at this point.)

Github.com
This is an online community where you can sync your local git repositories, share your work with the world, and collaborate on projects. In most projects the GitHub repository serves as the "single source of truth" that contributors' local git repositories feed into and pull from. If you're a developer in training, you've very likely set up a GitHub account, but you may not know why it's useful or how to use it yet. This challenge can also help with that.

Pull Request (PR)
When you ask for your code to be incorporated into a repository on github.com, you open what is known as a Pull Request - a formal request for one of the repository maintainers to approve incorporating your code changes into the indicated branch of the main repository. The maintainer will look at your code (eventually) and usually do one of the following: approve the request, ask for changes, or close the request. If approved, your changes will be merged into the main repository and your code will become part of the project. A good thing about PRs is that you can practice them on your own repositories... for example, you can create a branch called develop and then open a request (to yourself) to pull the changes on that branch into main. So you have the option of doing a few practice runs before you try to open a PR against an external repository.

Open Source Software Concepts

1. Contributors: This is the set of users who have provided code, documentation, or discussion to the project in some way. Different projects have different guidelines about how can and cannot contribute, or what steps need to be taken before contributing. It's important to look for this information before doing any work, so that your efforts aren't wasted.
2. Maintainers: This is a subset of contributors who have administrative privileges in the repository, like the ability to approve pull requests, merge branches, or trigger workflows.
3. Contributing Guidelines: Many of the larger open source software projects have an official CONTRIBUTING.md file that goes over the rules of who can contribute and how, and provides helpful information on how to get started developing on the project. On smaller projects, this information is often included in the overall README.md file for the repository instead. In some cases, you may need to reach out to the repository owner for more information on whether you can contribute and how you can set up your local development environment.
4. Templates: Large projects will often ask you to submit your PR using a specific template, or to name your commits or branch following a particular structure. It's important to know that these rules may exist, and follow them if you can find them, so that your PR isn't rejected.

Git Concepts

1. Commits: These are snapshots of a project's file structure and the contents of those files. Instead of tracking every single change you've ever made to a file, git allows you to make as many changes as you want and then simply commit the difference between your current file and the last snapshot (last commit) into the repository's "memory." This can be counterintuitive if you're new to version control software -- you need to actively commit your changes in order for the software to be able to remember them after you do additional work in the future! Your commit history is public on any public projects you contribute to (including your own), so keep that in mind when deciding what commit message to write. Though we all have at least one less-than-stellar commit message written out of haste or frustration (see below.)

1. Rebasing & Fast-Forwarding: You may hear these terms as you progress in your project. Going in, all you need to know is that they are ways of reconciling branches that have different commit histories. For example, maybe the primary repository has a develop branch that you copied and have added Commit A to, and you are working on Commit B. But, while you were working on Commit A, Commits C, D, and E were merged into the primary repository's develop branch, and they change enough that it would make sense to have those changes in the version of the software that you're working on (but you're also not quite ready to ask to merge Commit A back into the primary.) In this situation, you will have to decide the best way to incorporate Commits C, D, and E into your local repository.
2. Merge Conflicts: When you open a Pull Request, or when you try to pull new commits from the primary upstream repository into your own, you may encounter something called a merge conflict. This means that the changes are significant enough or the branches are divergent (different) enough that the version control software can't figure out how to incorporate your changes in. Many merge conflicts can be resolved by the right rebasing or fast-forwarding strategy, but sometimes it's necessary to manually resolve the conflict by directly editing each file where a conflict exists.
3. Branches: When working on a large project, it's customary to make your own branch before you start making your particular changes. Many repositories have guidelines on what to name your branch (usually some combination of your initials, what type of work you're doing, and a brief description - i.e. jc/fix-octal-literal-duplicate-error) Paying attention to these rules will help things go smoothly and will make you look like more of a pro.

GitHub Concepts

1. Issues: The easiest way (and often the only way) to contribute as a totally new community member is to open a PR that fixes an issue in the repository. Issues track a variety of topics ranging from feature requests & general discussion, to bugs (something isn't working as intended) and chores (something needs to be refactored or upgraded to prevent obsolescence and avoid future bugs.)
2. Labels: Issues can be tagged with different labels that can help you assess whether they are something you might help fix or not. For example, "good first issue" usually means that something can probably be tackled by a first time contributor. Sometimes you'll also see issues tagged with the label "easy" or "low effort". The label "help wanted" often also means that contributions are welcome.
3. Assignees: The assignees of an issue are shown in the top right corner. If an issue is assigned to someone, that often means that person is working on fixing the issue - and that if you were to begin working on it, you would potentially be duplicating their efforts. Since most of this work is on a volunteer basis, no one likes to commit their time to something only to learn that it was in vain! At the same time, if you see an issue that is assigned to someone and there have been no draft PRs or discussion in several months, most likely that assignee has abandoned the issue and you can ask the maintainers if it can be reassigned to you instead.
4. Forks: To work on an open source software project on GitHub, the first step after identifying an issue you want to tackle is to fork the repository - this adds a copy of the main repository at that particular moment in time to your personal GitHub account. (As the primary repository has commits added to it through pull requests, you'll need to update your copy accordingly by pulling in and merging the changes.) Once you've forked, you can clone the repository to your local development machine, create a new branch for your changes, and start work using your preferred IDE.

So there you have it -- some fundamentals that you need to know before you start your challenge. In my next post, I'll walk through of the 'find issue -> fork -> develop > contribute' process now that we've got the vocabulary down, as well as some of the variation you might experience from repository to repository in terms of how things work.