Contributors' Guide

Hey! Interested in helping out with the project? We’d love your help.

Both the project’s content and code to power it are stored in a GitHub repository. As such there are two types of work going on in parallel: editorial and technical. You can help out with either, or both! We plan and track work that needs doing in the issue tracker of our repository.

If you’re new to Git and GitHub, there are a wealth of resources on their website to get used to the basic technical concepts involved. Don’t worry if you’ve never touched a line of code before - you can still contribute!

Ways to contribute

Collecting Information

We’ve only collected a subset of all the shows the New Theatre has put on over the years. We need people to reach out to the alumni community and gather both memories of past shows and events and physical media from the time.

If you fancy helping out, let one of the editors know by sending us an email at history@newtheatre.org.uk.

Issues

Listing of issues

We use numbered issues to track both technical and editorial work that needs doing. The listing of open issues is public and can be found in our GitHub repository. Each issue can be a quick to-do list item, which is quickly ticked off, or a hub for discussion over a complex task.

The best way to get started is to read over what’s currently open and start commenting on issues that interest you.

Creating a new issue

Spotted an error on the site, have some information to share, or want to start a discussion on a particular topic? You need to create an issue. Be as descriptive as possible. For example, if the issue involves a problem with the site try and include screenshots or instructions on how to reproduce it. Other contributors can then comment and someone can take a crack at fixing the problem.

Making improvements

Git is a version control system, we use it to keep track of changes to the project’s files. This is a similar system to that used to track the history of articles on Wikipedia. Every change made to every file on the site is logged in a commit, and when you’ve made one or more changes (commits), it can then be merged into the site with a pull request.

Branching and making changes

The process of getting a change committed and a pull request opened may seem daunting at first, but stick with it. Once you’ve done it the first time it’s not too bad – honest!

Forking and branching

Firstly you’ll need to create your own fork of the respository on which to work. This is your own version so you can make your changes without worrying about affecting the main site.

Head over to the repository and hit the Fork button at the top-right. You’ll need to create a free GitHub account if you don’t have one already. Now you’re ready to start editing!

Using the web interface (github.com)

  1. Find the file you want to edit. Shows are stored in the _shows folder, people in _people, etc. See the Editors’ Guide for more information on actually making your edit and how the files are arranged. The Find file button is quite useful for this.
  2. Click the pencil in the top right to start an edit.

Making edits locally on your computer (command line)

This method requires a certain amount of technical knowledge but is a lot more flexible. It uses Git on the command line, and there are additional guides for getting started there.

  1. Fork the project by clicking “Fork” in the top right corner of newtheatre/history-project.
  2. Clone the repository locally git clone https://github.com/<your-username>/history-project.
  3. Create a new, descriptively named branch to contain your change git checkout -b my-awesome-change.
  4. Using your preferred text editor, make your changes. See the Editors’ Guide for more detailed information on this and the text editors we use.

Making edits locally on your computer (graphical methods)

The command line isn’t for everyone, and that’s why other bits of software exist. We’ve tried Gitkraken and GitHub Desktop, and the Git website has a full list of options.

The concept is exactly the same as above: clone, branch and commit.

Building the site locally

By editing on your computer, you can run the entire site and preview changes before pushing them to GitHub. You should have a good knowledge of Git and the command line before doing this.

See README.md for up to date install instructions.

Getting the site running on your machine locally is easy to do on macOS and Linux. It can be done on Windows, but it’s tricky. The website Run Jekyll on Windows has a full tutorial on how to do this, or you can try using Docker.

Writing a good commit message

Using git we can see what changed in a particular commit, but a good commit message can tell us why. This is very important for the future when other editors will be updating your work. In the case of show data, they’ll need to know your sources and how credible the information you’ve gathered is.

When writing commits, try and adhere to the following rules:

  1. Limit the subject line to about 50 characters.
  2. Capitalise the subject line and do not end it with a full stop.
  3. Use the imperative tense in the subject line.
  4. Use the body to explain what and why.

Your subject line should tell us what you’ve done.

Add crew members to Hamlet (82)

Note we’ve used the imperative Add crew, not the indicative Added crew. To remove any confusion, here’s a simple rule to get it right every time. A good subject line should always be able to complete this sentence: If applied, this commit will <your subject line here>.

The body, or description should tell us why you’ve done it:

Got information from alumnus Fred Bloggs (BA Archaeology 1984). Spoke on the phone.

Will close #123

Note we’ve specified the years of both the show and the alumnus. This prevents confusion between items with the same name. Also note the referencing of an issue number, doing so in this manner will automatically close the issue when the commit is merged into master.

When adding new or changing current information include a source, even if it is yourself.

For further reading on this topic please see this excellent article: How to Write a Git Commit Message.

Submitting a pull request

Now you’ve made one or more commits it’s time to open a pull request to request a project maintainer to pull in your work to the main repository.

Do bear in mind the smaller the proposed change, the better. If you’d like to propose two unrelated changes, create two branches and submit two pull requests.

All pull requests get built to a testing environment, and go through some automated code checks. Ensure you have a verified email address with GitHub otherwise your changes will not trigger a build.

Just like commits, it’s possible to add a subject and message for your pull request. It’s useful here to explain what you’ve still got to work on in the message. For example, you could make a pull request for a work in progress (denoted by WIP in the subject) so that others know you’re working on it, but that it’s not ready for merging.

As other editors of the site will be reviewing your pull request, include in the message what you’d like to draw to their attention such as specific feedback or any help you need.

For further reading on pull requests do read Ben Balter’s article: The six types of pull requests

Submitting a pull request via the web interface (github.com)

  1. When commiting your changes select “ Create a new branch for this commit and start a pull request”. Enter a short descriptive branch name.
  2. Click “Propose file change”
  3. Give your PR a descriptive title and description.
  4. Click “Create pull request”

That’s it! You’ll be automatically subscribed to receive updates as others review your proposed change and provide feedback.

Using one of the other software-based options have a very similar process to the one above.

Submitting a pull request via Git command line

  1. Push the branch up (git push origin my-awesome-change).
  2. Create a pull request by visiting https://github.com/<your-username>/history-project and following the instructions at the top of the screen.

Testing Pull Requests

There are a number of ways to review an editor’s pull request, and this can depend on what they’re looking to get out of the review. The basics involve the automated checks, as well as adherence to our style guide, comments, efficiency, and so on.

You can also make sure the code runs effectively by running it on your own computer by building it, or viewing the edited pages in the test environment. A link to this test environment will be on the pull request page, once it’s built successfully.

Becoming a Contributor

If you decide making these kinds of edits and contributions is for you, we’d love to have you as part of the team! We’re all volunteers here, and once you’ve had a few pull requests merged you’ll be able to join the list of contributors. This means you won’t have to make your own forks, and can edit the finer details of issues and pull requests.

Anything else

See the other pages here for more detailed information about each section of the site.

If you get stuck, or want to help out another way, send us an email at history@newtheatre.org.uk or get in touch with any of the editors.