Skip to content

AO3 Coding: Your First Pull Request

Jump to bottom Edit New page
sarken edited this page Nov 29, 2022 · 10 revisions

Note: This is the second part of a four-part tutorial aimed at AD&T Coding Volunteers. Not all of the information will apply to contributors who are not official volunteers, and it may include links to internal documentation and references to tools (e.g. Slack) that are only accessible to official volunteers.

Please do not edit this page unless you are an official volunteer. Instead, contact AD&T using the email address on the bottom of this page to suggest changes.

This page will guide you through the process of using Git to make and submit changes to the Archive code base using the "fork and pull" development model. It assumes you are already set up with Jira, GitHub, and a development environment, per the instructions in AO3 Coding: Getting Set Up.

Table of Contents

Find an issue to work on

Before you can start coding, you need to choose something to work on! We track our bugs and features in our Jira issues database, which we'll discuss in depth in part four of this training tutorial.

  1. Find an open, unassigned issue you want to work on, either by browsing that list or asking in the #ao3-adt-public Slack channel
    • If you choose an issue from the list, check in Slack to make sure it's a good issue to work on (especially if it's one of your first)
  2. Assign yourself to the issue using the Assign to me option in the Assignee field
  3. Select In Progress from the options at the top of the issue

Start your coding session

  1. Open up a shell window on your computer
    • Mac: Terminal, Windows: Git Shell, Linux: shell
  2. Navigate to your otwarchive folder: cd ~/Some/Folder/on/Your/Computer/otwarchive
    • If you're using a webdev, you'll need to log in and then navigate to the directory:
      • ssh [yourname]@[yourname].archiveofourown.org
      • cd ~/app/current
  3. In the text editor of your choice, open the file(s) you want to edit
If you're using a webdev and you get a "Bad gateway" error, restart your unicorns: start_my_unicorns

If you need to run background jobs (for instance, delivering mail or running challenge matching), you will need to start up Resque. It will need to keep running, so open a second shell window and start the queue: QUEUE=* bundle exec rake environment resque:work

Coding workflow

You will manage your code with Git, the version control system behind GitHub. Git lets you group your code into branches and helps combine your edits with others'.

This is the cheatsheet version of the commands you will generally want to use; below we will explain them in detail: 

  git checkout master
  git pull upstream master
  bundle install
  bundle exec rake db:migrate
  git checkout -b AO3-1234   # replace 1234 with the issue number
  # work, save (on your own computer)
  git status
  git add file/that/changed.rb
  git commit -m "AO3-1234 short message"  # starting the message with the issue number is a good idea
  # go back to work, save, repeat as often as desired
  git checkout master
  git pull upstream master
  git push origin master
  git checkout AO3-1234
  git merge master
  git push origin AO3-1234

git checkout master

Here you are checking out your personal local copy of the master branch of the Archive. This marks it as your current HEAD or active branch, i.e., the one you are working with at the moment.

git pull upstream master

Now you are "pulling" all the changes that have been made in the upstream repository's master branch into your master branch. This ensures you have all the changes made to the Archive code since your last update.

Note: To set up your upstream remote, run git remote add upstream https://github.com/otwcode/otwarchive.git.

bundle install

This will update all the gems and plugins the Archive is using with changes made since the last time you updated.

Updating Ruby

If you run bundle install on webdev and get an error saying Your Ruby version is 2.a.b, but your Gemfile specified 2.x.y, you will need to update Ruby:

  • reset_rvm
  • cd ~/app/current
  • gem install bundler
  • bundle install
  • start_my_unicorns

bundle exec rake db:migrate

This will run all the database migrations (that is, changes to the database) that have been made since the last time you updated.

git checkout -b AO3-1234

This command creates the branch called AO3-1234 and makes it your current active branch. It is branched from the point you were when you issued this command.

  • Always include the Jira issue ID for your branch name (e.g. AO3-1234, AO3-1234_short_description)
  • If you just need to switch to an existing branch named AO3-1234, you can use git checkout AO3-1234
NEVER NEVER NEVER commit changes to the master branch! Always commit your code to a separate branch. If you accidentally do commit changes to master, ask an AD&T staffer or other senior coder to help you undo it.

Work and save

This is where you actually write some awesome code on your own computer using the skills you acquired from any of the Ruby tutorials linked in the Getting Started Guide.

When you save changes to a file, those changes are in your working directory -- your own filesystem. You'll need to stage, commit, and push these changes before anyone else can see them.

git status

This command will show you a list of files that have changed.

  • Changes in your working directory will be listed under the heading Changed but not updated
  • If you want to see the exact changes to all the files in your working directory, use git diff
  • If you want to see the exact changes to a specific file: git diff file/that/changed.rb
If you ever forget what branch you're on, the status command will tell you that, too!

git add file/that/changed.rb

Once you have finished writing your code, you want to add or stage your changed files -- this marks it as something that you want to have included in your next commit to the Archive.

  • If you're deleting a file, use rm instead: git rm file/you/removed.rb
  • You can also add or remove multiple files at once by listing them one after the other: git add file/that/changed.rb another/changed/file.rb
  • If you want to add all the files that have changed in your working directory, use git add .
If you run git status after this step, you'll notice the staged files are now under the heading Changes to be committed.

git commit -m "AO3-1234 short message"

When you are happy with your changes, you should commit them. Generally you will want to commit whenever you finish work for the day.

Note: This only adds your changes to the current branch on your local repository. No one else can see your changes until you push to your GitHub repository.

A note about commit messages

If you can use a short message, less than about 50 characters, do so using the git commit -m "My short message" format. Commit messages should include the Jira issue number and a meaningful explanation. This makes it much easier for future coders to understand why changes were made.

If you feel like you need a longer message, you can do so with nano:

Repeat as needed

You can repeat the last three steps as often as you like. For instance, you might be working on a really complex project over the course of months. Don't wait until it is all done and working to commit -- commit your changes regularly as you go.

git checkout master

Wait -- haven't we done this before?

We have, but every time you return to your branch, it's a good idea to combine your changes with all the other edits everyone else has made in the meantime. It is also necessary to do this before you submit your changes to the main Archive.

To do this, first you start by checking out the master branch again and making it the active one instead of your AO3-1234 branch.

git pull upstream master

Like before, you now get the newest version of the Archive code.

git push origin master

You are now pushing your master branch (which has all those updates you just pulled and should match the main otwcode copy of the Archive code) up to your own personal GitHub account. This keeps your GitHub master branch in the same state as the main Archive's master branch, so that when you upload your changes, if someone then wants to see what you have changed, they can do it looking just at your own GitHub repository.

git checkout AO3-1234

Now you switch back to the branch you want to send on to the main Archive repository.

git merge master

The merge command will combine your changes with other people's changes to the master repository. This is where you may run into conflicts -- for instance, if someone else happened to edit the same file you did. When you run into a conflict, please come to Slack and get help the first few times.

git push origin AO3-1234

This uploads your changes to your GitHub account.

Note: If you've already pushed the changes once and you perform a second merge or rebase, it can cause problems that are very case-by-case dependent. If you run into any trouble, don't be shy of coming to Slack and getting help.

You are now ready to submit a pull request!

Submitting a pull request

Note: Only contributors with write access to the upstream repository (i.e. those who can merge pull requests) can apply labels to pull requests. If you don't have permissions, you can skip any labeling steps and someone will be along to do it for you.

Now that your GitHub repository includes the branch with your changes, you'll create a pull request to let the maintainers know that you have some changes they might want.

  1. Go to your otwarchive fork on GitHub, i.e. http://github.com/[your GitHub name]/otwarchive.
  2. Select the branch you created for this issue and follow GitHub's instructions to create a pull request.
    • Be sure to mention the issue number and a short description in the title of the pull request. The issue number will be filled in automatically if you named your branch AO3-1234. The title is included as a comment later, and it can help future work if this is descriptive.
    • Include a link to the Jira issue you worked on in the comment area of your pull request to make life easier for the reviewers and who will merge your code and the testers who will test it.
    • Set the GitHub label to "Awaiting Review" so our reviewers know it's ready and can find it easily, if you have permissions.
If you've already opened a pull request and find something in it that needs to be changed, don't worry! You can go back to work on the same branch you've been using, commit your changes, and then push them up to GitHub. Your pull request will be automatically updated with a note about your new commit.

After submitting your pull request

  1. The Status of the corresponding Jira issue will automatically update to In Review within an hour of your pull request submission
    • If it doesn't, choose Pull Request Submitted... from the Workflow dropdown, which will change the issue Status to In Review
      • If Pull request submitted... is not an option, you will need to choose Started work first -- then the proper option will appear
  2. Add the following information to the Jira issue:
    1. A comment for the Quality Assurance & Testing team, including numbered steps on how they can verify the issue is fixed or find the new feature you have added (if this is not already outlined in the issue-text itself)
    2. A comment for the release notes, explaining briefly and in simple terms what you have done
  3. One of the other coders will review your pull request by leaving comments on GitHub
    • If it needs more fixes, they will point out what needs work and label the pull Reviewed: Action Needed
    • If it's ready to be merged, they will label the pull Reviewed: Ready to Merge
    • If you make any fixes, after you push them, remove the Reviewed: Action Needed label and apply the Coder Has Actioned Review label, if you have permissions
  4. Once your code is ready, a senior coder will merge it and the Jira Status will automatically be updated to Merged
  5. QA&T will check to make sure that the issue is really solved and update the Status
    • If they mark it Ready for Release, it is good to go to the real Archive! \o/
    • If they mark it Broken on Test, you have more work to do:
      • If you can fix it, submit a new pull request
        • On the Jira issue, choose Pull request submitted from the Workflow dropdown. This sets the issue Status to Broken on Test-SPR so our reviewers will give it priority
        • You can also apply the Priority: High - Broken on Test label on GitHub to make sure you get the reviewers' attention, if you have permissions
      • If you can't fix it, please make sure AD&T staff knows so they can help
      • If you can fix it, but not in time for the current deploy, let AD&T and QA&T know and they'll decide whether to deploy it as-is or roll it back

Summary

To summarize, when submitting a pull request:

  • You should be the Assignee on the Jira issue
  • The branch name should include the issue number
  • The commit messages should include the issue number
  • The pull request title should include the issue number and a brief description
  • The pull request comment should include a link to the issue on Jira
  • The pull request should be labeled Awaiting Review (if you have permissions to set labels)
  • The Jira issue Status should be In Review
Code reviewers generally won't reject a pull request just because it's missing some of the information discussed in this tutorial, but they might ask you to add it or remind you to include it next time. (Drive-by code review and discussion of anybody else's code is always welcome -- we can all learn more -- but please remember to keep it constructive.)

When you can't figure out what to do

Aside from asking in Slack or just Googling, we highly recommend searching or even asking on StackOverflow, which is a great resource for getting coding help.

More information about GitHub

For in-depth explanations and troubleshooting hints, refer to the next part of the Getting Started tutorial: More About Git

Automated testing

Refer to the Automated Testing.

For much more background, please refer to Introduction to Testing.

If you have any questions regarding code development, please don't hesitate to send an email to otw-coders@transformativeworks.org and we will try to get back to you as soon as possible!

Navigation

For Official Volunteers
Clone this wiki locally