Jekyll Theme Primer Spec

Contributing to the Primer Spec Theme

This document was adapted in part from the corresponding documents from the original Primer theme.

Contents

Looking for support?

We’d love to help. Check out the support guidelines.

How to report a bug

Think you found a bug? Please check the list of open issues to see if your bug has already been reported. If it hasn’t please submit a new issue.

Here are a few tips for writing great bug reports:

How to suggest a feature or enhancement

Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and goals of the project. It’s up to you to make a strong case to convince the project’s developers of the merits of this feature. Please provide as much detail and context as possible, including describing the problem you’re trying to solve.

Open an issue which describes the feature you would like to see, why you want it, how it should work, etc.

How to propose changes

Here are a few general guidelines for proposing changes:

Dev Onboarding

Read the Dev Onboarding doc to familiarize yourself with the organization of the Primer Spec repository and how the theme works in general.

Typical workflow

  1. Fork the repository.
  2. Clone your repository to a local directory.
  3. Create a new branch with an appropriate name. (git checkout -b feature/my-feature)
  4. Bootstrap your local environment.
  5. Make some changes and create commits.
  6. Push your branch to GitHub. (git push -u origin feature/my-feature)
  7. Open a pull request from your branch to the EECS 485 repository’s develop branch.
  8. Wait for a project member to review your changes and determine its semver label.

Bootstrap your local environment

  1. Ensure that you have a version of Ruby later than 2.4.0. If you’re on a Mac, you may need to run brew install ruby first.

  2. Ensure that you have NodeJS installed.

  3. Run script/bootstrap.

    $ ruby --version
ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-darwin18]
$ pwd
/seshrs/primer-spec
$ ./script/bootstrap

  4. Run script/server to begin the Jekyll server. By default, the site is served at http://localhost:4000/. (It monitors changes you make to most theme files and automatically rebuilds the website.)

Run tests

The theme contains a minimal test suite, to ensure a site with the theme would build successfully. To run the tests, simply run script/cibuild. You’ll need to run script/bootstrap once before the test script will work.

Adding new subthemes

Primer spec allows website visitors to change the appearance of the website by selecting from built-in subthemes. The themes are implemented by changing CSS variables used in the base stylesheet. The themes are declared in JavaScript (see bella.theme.ts, for example).

To create a new subtheme:

Pro tip: Upload screenshots of the new subtheme to make it easier to review your Pull Request.

Maintenance & Release

This theme is used by several courses at the University of Michigan. If a PR proposes major design changes, it’s usually a good idea to keep the courses’ staff aware of the changes.

Some notes about maintaining this project:

  1. Create a new release by syncing develop and main
  2. Bump the version if required in Pull Requests

Releasing for the next semester

Also known as a “release freeze”.

The latest stable version of the theme is available on the main branch. (This is the default branch selected by the Jekyll Remote Theme, the plugin that allows this theme to be used on course websites.) This branch is not changed during semesters at the University of Michigan while courses are in-session. This is to ensure that all project specs throughout the semester have a consistent appearance.

The develop branch is the default branch for the GitHub repository, and hosts the latest accepted code changes to the theme. This branch is usually ahead of main. Between semesters at the University of Michigan, changes from the develop branch are merged with main to keep them in sync.

To publish a new release, first prepare the main branch and sync with develop by initiating the release GitHub Actions workflow from the Actions tab.

If the GH Actions workflow fails, expand this section for detailed steps.
  1. Pull the latest versions of both branches.
$ pwd
/users/seshrs/primer-spec
$ git checkout develop
$ git pull
$ git checkout main
$ git pull
  1. Merge develop into main. (If you like signing your commits, don’t forget to add the -S flag.)
$ git checkout main
$ git merge -S develop
  1. Build the latest JS source
$ script/cibuild
$ git add assets
  1. Freeze the version (remove the .d at the end of the version string) by running:
$ script/version freeze
$ git add VERSION
$ STAGE_STATIC_ASSETS=true git commit -S -m "Freeze version v1.2"
  1. Push your changes to GitHub with git push.

Finally, tag the release:

  1. Visit the releases page. Note the most recent release’s version number (for example, 1.0.0+fa19).

  2. Also specify the upcoming semester after the + symbol — this is metadata and is not parsed as part of the version number. (For more about versioning, see Semver.)

  3. Click the “Draft a new release” button. Specify the version number. Title and description are optional. (Switch the “target branch” to main. That said, the two branches should be in sync at the time of release so this should not really matter.)

Bumping the version in Pull Requests

Primer Spec uses semantic versioning to communicate the scope of changes between releases. Correct versioning provides for backwards compatibility, so that documents generated with older versions of Primer Spec still work.

Imagine labeling every change to this project with the following labels (listed in increasing order of precedence):

Except noop changes, all changes require the version to be bumped from the current release freeze. A version bump IS REQUIRED if a code change is not preceded by another code change of similar or higher precedence.

This means that:

To propose a version bump, use the version script. For example:

$ script/version bump minor

The version bump must be done in the same Pull Request that proposes such a change. (If the Pull Request is merged without bumping the version, the previous older version of Primer Spec will lose its backwards-compatibility guarantee!)

Modifications from Primer

Here are key changes made to the original Primer theme to add a sidebar:

Further reading: DEV_README.md

Code of conduct

This project is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Additional Resources