After you orient yourself with your project, you need to decide what you’re going to work on for your contribution. For the example in this book, we choose issue #2 in the To do column of the project board: Change the title and tagline.
Other good candidates are any issues that were opened with the label bug, help wanted, or good first issue because these issues are typically urgent for owners or good entry points for contributors.
TIP
This section assumes you already have a repo cloned onto your machine. The examples in this section use GitHub Desktop and Atom to resolve the issues. If you need guidance in cloning a repo or getting the project set up in GitHub Desktop or Atom, see Chapter 4.
1. Creating a branch for your contribution
Before you modify or add code to any project, whether a private solo project you own or a large open source project, we highly recommend creating a specific branch where all the code you write will be contained. Branching is a Git function that essentially copies code (each branch is a copy of the code), allows you to make changes on a specific copy, and then merge your changes back into the main (master) branch.
When you create a branch, Git doesn’t actually copy all the code, which would be time consuming and inefficient. Git does something way smarter, but the specifics of what it does aren’t important to day-to-day usage of Git, which is why we say Git creates a copy of the code. It’s not technically correct, but it’s conceptually correct. It’s a useful mental model for branches.
Creating a branch for your changes gives you a safe space to try out solutions and make mistakes without threatening your project’s integrity. If your solution is taking you down a wrong path, you can simply delete the branch, create a new one, and start over. Creating a branch helps your master branch remain in an always working state because you only merge your code into the master branch when you’re confident it doesn’t introduce any new problems and/or accurately solves the problem you were targeting.
Different projects and people use different nomenclatures for their branches. In this book, we use a short description of the code modifications to name our branches. The folks who contribute to Atom, which is an open source project hosted on GitHub, often put their initials in front of their branches before a short description. You can see this nomenclature on the Atom GitHub repo at https:// github.com/atom/atom/branches. Before creating a branch on a public repo, check out how other contributors have been naming their branches or see whether the CONTRIBUTING.md file contains any guidelines.
This book uses GitHub Desktop to manage projects on your local machine and Atom as the primary text editor. If you need to set up these two applications, see Chapter 4.
To create the branch for your contribution, follow these steps:
- Verify the repo you cloned.
Open the GitHub Desktop application and verify that the top left drop-down list has your website repo selected. Figure 5-5 shows the repo correctly selected.
- Create a new branch.
Click the branch drop-down list in the top center of GitHub Desktop and click the New Branch button (see Figure 5-5). When you click the New Branch button, a dialog box appears.
- Give your branch a name.
Type a name for your branch. In our example, we use new-title-and- tagline because that is the change we plan to make.
- Click Create Branch.
The dialog box closes, and you switch to the new branch. Figure 5-5 shows the current branch as master, but when you complete this step, it should change to your new branch name. The button at the top right of GitHub Desktop also changes from Fetch origin to Publish branch.
- Publish your branch.
Before making any changes to your branch, we recommend publishing your branch to GitHub.com. That way, as you start to modify or add code and push it to your branch, you won’t lose any your work. Click the Publish branch button on the top right of GitHub Desktop. When the branch has been successfully published, this button goes back to the Fetch origin button, just like it is in Figure 5-5.
- Open your project in Atom.
Open the Atom application and verify that your project folder is open.
A tree-view of your project appears in the left hand column. Notice that the branch selector at the bottom of the Atom application window now shows the branch name. Figure 5-6 shows the correct branch checked out in Atom.
If you click the branch selector in Atom and change the branch, the branch in GitHub Desktop correctly changes to the same branch, and vice versa!
2. Confirming your branch is published
Before writing code that you want to keep, confirm that you correctly published your branch and are able to push to the branch. If you’re working on the same project, on the same computer, then you most likely are still properly set up. But if you’re contributing to a project for the first time or you have just set up a new computer, you should consider confirming you’re able to contribute.
This section shows you examples of contributing to the GitHub website repo https://github.com/sarah-wecan/sarah-wecan.github.io using GitHub Desktop and Atom.
To get started, follow these six steps:
- Click a file in the file tree in Atom.
Th file opens in the editor. Figure 5-7 shows index.md open.
2. Modify the file
Don’t make a lot of changes at this stage because the goal is to confirm you’re able to push changes to the branch that you published.
3. Save the file.
Choose File o Save to save your changes. When you click Save, The color of the file in the file tree changes, and the Git button changes to indicate that a change occurred (see Figure 5-7).
- Open the Git tab by clicking the Git button.
You see the changes in the unstaged area.
- Stage and commit the changes.
Stage all commits by clicking the Stage all button and write a commit message. Then click Commit to master. Figure 5-8 shows this step. After you click the Commit button, your commit appears in the commit list below the button, and a button that allows you to undo the commit appears.
- Push and merge the changes.
The Sync button on the bottom bar to the right of the branch name changes its action based on your current context. Prior to creating the commit in the previous step, the button was labeled Fetch (see Figure 5-8). It now is labeled Push 1 to indicate that you have one commit that you can push. Click Push 1 to push your changes to GitHub. Then open GitHub.com and go to the repository.
In this example, the repository is https://github.com/sarah-wecan/ sarah-wecan.github.io. You now see a suggestion to open a pull request (see Figure 5-9).
Create and merge the pull request. Chapter 3 gives a brief introduction to how to merge a pull request, and Chapter 8 gives an in-depth view of what you can do with pull requests if you need additional guidance.
Sometimes, pull requests can create merge conflicts. See the sidebar “Resolving simple merge conflicts” for insight on how to resolve them.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.