CONTRIBUTING.md

Getting Started

Mirador uses node.js and a build system to assemble, test, and manage the development resources. If you have never used these tools before, you may need to install them.

1. Install Node, if you haven't already (available at the link above)
2. Clone the mirador repository (if you haven't already done so above); git clone https://github.com/ProjectMirador/mirador.git
3. On the command line, go into the mirador folder
4. Install all dependencies with npm install. Run npm start

npm start will run a local server that is available at localhost:8000.

How to Contribute

Making Changes

Contributions are always welcome, however, it will always be helpful to begin any large change by submitting an issue, or reviewing an existing issue. This will give the developer community a chance to point you in the right direction, let you know of any connected issues that may not be obvious, and provide feedback about how the feature might fit into the current roadmap. Contributions that involve major changes to the UI will need to have a design audit completed before they can be fully integrated. See the Design section below for information about the design review process.

To make a contribution, update the master and develop branches. The master branch is the current stable version, though each release also has a tag. The develop branch is the current working branch into which pull requests will be merged for upcoming releases. After creating a new branch off of develop, make a discrete change representing a bite-sized chunk of work, and write an informative commit message. We do not enforce any rebasing strategy, but we may ask you to rebase if you have many small and intermediate commits with unhelpful messages. "One commit per PR" is a worthy goal.

Making Small Changes

Even small changes should follow the branching strategy outlined above, though they may not need a long discussion. It may still be helpful to create an issue for them, though it is not strictly necessary.

Updating Documentation

Mirador currently uses gitbook for its documentation. You can find the current documentation in the docs folder on any branch. The docs will be re-generated for the website when submitted, and kept up to date with the current master. Documentation updates are always welcome, and should be included with any fundamentally new changes. For general documentation submission, checkout the master branch and branch from it into a documentation branch. Add to the gitbook files stored in the docs directory.

Updating and Running the Project

Install all dependencies with npm install. Run npm start. This ensures that any new changes from the remote are picked up in your development build.

Create a branch for your work: e.g.: git checkout -b my-feature-branch or git checkout -b my-bug-fix

Usual Development

Once you have built the necessary files and created a branch for your feature or bug fix work, you are ready to code.

Live interactive reloading of the browser each time a file is saved is enabled and used in the npm start command. Note that this will require middleware or a livereload browser extension.

Submitting Your Contribution

Publishing a New Release

1. Ensure all Tests Pass

All development occurs on the pinned development branch. Ensure that all tests with merged features are passing in travis before moving on to the release process. The release consists of merging the main development branch with master, therefore all changes must be fully integrated and functioning in the development branch. Do not create any new release branches until the current release has been merged into master.

2. Change version number in package.json

If the version number included in the package.json does not already accurately reflect the version to be released, be sure to increment the number according to SemVer conventions. Bump the third number for a small patch that does not change or add any new functionality; bump the second number if the branch includes any new features that do not interfere with or change existing features; and bump the first ("major") version number if the changes to be released break or change the API for existing functionality.

3. Merge Develop into Master

For example, ensure that all feature branches (such as "fix_annotation_bug#1234") have been merged into the develop branch as Github Pull Requests, and then merge the develop branch (which will be the default branch) into master through the Github interface (through a PR).

4. Create a New Local Tag

After all new changes have been merged into master, checkout master locally, and create a git tag for the new version: git checkout master git tag v[VERSION_NUMBER] This will give the current state of the project a name and freeze it in time.

5. Push Tag to Github

Now push the tagged version to github (from master): git push --tags

This will cause the new version to appear under the "releases" section of the github project page, and will allow npm to access it in the next step.

6. Create Build and Add it to the New Release

7. Update the gh-pages Demo Instance to Show Off the Latest Features

8. Update Release Notes

Using the github commit log, compile a bulleted list of the features and changes added to the new release.

9. Publish to NPM

Assuming the commiter has access to the project's package management account on npm, publishing the most recent version requires logging into npm on the command line. Then simply type npm publish to post the new package version to the registry. To configure your npm user locally, refer to the npm-adduser documentation.

10. Announce New Release on the Mailing Lists and Slack

Design Review

Design review can happen in one of two ways, though both ways start with an issue or issues describing the interaction requirements. Once an issue has been created for a new UI-heavy feature, whether or not a prototype is complete, the feature goes up for design review. This is generally a three-step process: