Making Technical Contributions

Developing this site locally

If you intend to make a technical contribution to the underlying templates for this site, please make sure you follow the best practices outlined here.

(If you are looking to make a contribution or edit to the content of a lesson, see our contributor guidelines instead.)

This brief guide assumes that you are generally familiar with git, GitHub, and Jekyll. PH has two great introductions to these technologies:

• GitHub lesson
• Jekyll lesson

If you have any questions about this guide, or about a potential technical contribution, create an issue and tag the technical development coordinator for PH, @mdlincoln.

1. Forking the repository

We welcome contributions from everyone via Pull Request. To start that process, fork the repository so you can begin coding in your own copy of it.

NOTE FOR CURRENT EDITORS: If you are already added as collaborators to this repository and are able to push commits directly, please feel free to commit minor changes (typo fixes etc.) directly to this repo. However, major additions involving moving or erasing files, editing Jekyll _layouts or _includes, or making structural changes to any YAML files, should be done via PR, so that another member of the team can review them before merging.

2. Setting up a GitHub pages development environment

This site is built via Jekyll, using GitHub Pages as a hosting service. This means that all code in this GitHub repo is processed by GitHub servers to produce the HTML pages that readers see. If you want to preview what this generated site looks like on your own computer, you need to make sure you are using the same versions of Jekyll and its dependencies that GitHub does.

1. Set up Jekyll dependencies.
2. Fork the programming historian repository, and clone that fork to your local machine.
3. Ensure you have the "bundler" gem installed by running the command:

gem install bundler

4. cd into your clone of the PH repository, and run the command bundle install. This will install all the additional necessary gems to keep you up to date with the gem versions being used on GitHub, and by the rest of the team.
5. Run bundle exec jekyll serve --watch to generate the site and start a local webserver. You can then preview the local version of the site by going to http://localhost:4000 in your web browser.

3. Push your changes and open a Pull Request

Once you've made your edits, push them back to your fork of the repository and open a pull request.

(Note: if you want to make a live preview of your changes for others to look at, see "Modifying baseurl in _config.yml" below.)

4. Check your PR status

We use Travis CI and htmlproofer to check that the site builds properly, and that none of the internal or external links on the site are broken. When you make a pull request (and, as a collaborator, when you push any commit), Travis will automatically try to build the site and check for problems. This usually takes a minute or two, and the results will appear as a green check mark, or a red X.

If your build has an error, you can click on the "Details" button to view the build logs. If you scroll to the bottom, you'll see an error report that may list URLs that led to unresponsive pages. If you can see how to fix it, then do! Otherwise, one of the PH editors will help resolve the problem. All build and broken-link errors must be fixed before any changes can be merged in to the site.

Best practices

Modifying baseurl in _config.yml

If you only need to preview your modifications on your own local machine, then you do not need to make any edits to _config.yml

However, you may want to push changes on to your online fork of the repository in order to create a live preview of your site shareable with others. If so, you will need to temporarily add a baseurl value to _config.yml that matches the name of your forked repository. By default, your fork will be named jekyll. (If you changed that fork name in your own repo settings, you will need to put that name in baseurl instead.) Add the following line:

...
url: http://programminghistorian.org
basurl: jekyll
...

This will allow image links and redirect links to correctly point to your own published fork at http://username.github.io/jekyll

When submitting your pull request, be sure to remove the baseurl line from _config.yml

Filenames with special characters

Some files in this repository have non-ASCII characters such as ñ. Some earlier versions of Git and OS X get confused by these Unicode characters, and will register that a file has changed when, in fact, none has. These errors can be addressed by running the following command:

git config --global core.precomposeunicode true

When in doubt, do not git add files with special characters unless you are certain that you have created or modified them.