Making Technical Contributions

Preface 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 core Jekyll files like _layouts or _includes, or making structural (as opposed to content) changes to any YAML files, should be done via PR, so that another member of the team can review them before merging.

Any substantial text changes to pages both in English and Spanish must be followed immediately by opening an issue describing the change and indicating the file for the Spanish editorial team.

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.

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.

5. Preview how your PR looks when built into HTML

The Programming Historian repository is currently integrated with the static site building service Netlify. Much like the Travis CI integration tests the internal and external linking structure of our site every time a new commit is pushed to the repository, Netlify offers a live web preview of pull requests and branches.

The site is currently mirrored at the address http://ph-dev.netlify.com. Any branches or pull requests are deployed on custom-named subdomains. For example, if you have opened a pull request with the number #123, then the live preview will be published at http://deploy-preview-123--ph-dev.netlify.com.

You don't need to memorize this pattern, however. If you open a new pull request, you will see a panel below the comments section that displays the status of Travis CI and Netlify builds. To open the Netlify build, click on "Show all checks", and then click on the "Details" link for the Netlify check:

Best practices

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.