Skip to content

Latest commit

 

History

History
248 lines (172 loc) · 11 KB

DEVELOPERS.md

File metadata and controls

248 lines (172 loc) · 11 KB

Accord Project Development Guide

Development Setup

This document describes how to set up your development environment to build and test Accord Project libraries.

Installing Dependencies

Before you can build one of our libraries, you must install and configure the following dependencies on your machine:

  • Git: The Github Guide to Installing Git is a good source of information.

  • Node.js (LTS): We use Node to generate the documentation, run a development web server, run tests, and generate distributable files. Depending on your system you can install Node either from source or as a pre-packaged bundle.

    We recommend using nvm (or nvm-windows) to manage and install Node.js, which makes it easy to change the version of Node.js per project.

Forking Accord Project repositories on Github

To contribute code to Accord Project, you must have a GitHub account so you can push code to your own fork of an Accord Project repository and open Pull Requests in the repository.

To create a Github account, follow the instructions here. Afterwards, go ahead and fork the specific Accord Project repository.

Keeping In Sync

It is good practice to always keep your origin/master in sync with upstream/master. You don’t have to, but it makes your life easier. Do your work in branches of your fork, and periodically sync up your master with the master of upstream as follows. You should definitely do this before creating a pull request.

    git checkout master
    git fetch --all --prune
    git rebase upstream/master
    git push origin master

Running the Unit Test Suite

We write unit and integration tests with Enzyme and execute them with Jest. To run all of the tests once on Chrome run:

    npm run test

Coding Rules

To ensure consistency throughout the source code, keep these rules in mind as you are working:

  • All features or bug fixes must be tested by one or more specs.
  • All public API methods must be documented with JSDoc. To see how we document our APIs, please check out the existing source code and see the section about writing documentation
  • With the exceptions listed below, we follow the rules contained in Google's JavaScript Style Guide.

Git Commit Guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history and git logs. But also, we use the git commit messages to generate the Cicero-UI change log.

The commit message formatting can be added using a version of typical git workflow.

Commit Message Format

Each commit message consists of a mandatory type, scope, subject, and footer. This is a specific format:

    <type>(<scope>): <subject> - <footer>

This allows the message to be easier to read on GitHub as well as in various git tools. Some examples:

feat(core): add API for direct drafting to slate - #559   // feature for core (cicero) that will add API for direct drafting to slate, from issue #559
fix(ui-markdown-editor): correct typo in readme - #274    // fix for ui-markdown-editor (web-components) that will correct typo in readme, from issue #274
chore(github): migrate travis ci/cd to gh actions - #4    // chore for github (markdown-transform) that will migrate travis ci/cd to gh actions, from issue #4
docs(README): add interaction test script                 // docs for README that will add interaction test script, from no issue

Revert

If the commit reverts a previous commit, it should begin with revert: , followed by the subject, where it should say: this reverts commit <hash>., where the hash is the SHA of the commit being reverted. A commit with this format is automatically created by the [git revert][git-revert] command.

Type

Must be one of the following:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Scope

The scope will be specifying the place of the commit change; the focal point of new code or best description for where changes can be found.

You can use * when the change affects more than a single scope.

Subject

The subject contains a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize the first letter
  • kept under 50 characters
  • no dot (.) at the end

Footer

The footer should contain reference GitHub Issues that this commit addresses.

GitHub Pull Request Guidelines

Pull Requests should consist of a complete addition to the code which contains value. Because the commits inside follow a pattern, the title should be an extension or summary of all the commits inside.

Pull Request titles should follow commit message formatting.

Formatting for the body is displayed in this example:

<!--- Provide a formatted commit message describing this PR in the Title above -->
<!--- See our DEVELOPERS guide below: -->
<!--- https://github.com/accordproject/techdocs/blob/master/DEVELOPERS.md#commit-message-format -->
# Closes #<CORRESPONDING ISSUE NUMBER>
<!--- Provide an overall summary of the pull request -->

### Changes
<!--- More detailed and granular description of changes -->
<!--- These should likely be gathered from commit message summaries -->
- <ONE>
- <TWO>

### Flags
<!--- Provide context or concerns a reviewer should be aware of, such as breaking changes -->
- <ONE>
- <TWO>

### Related Issues
<!--- Link any issues or pull requests relating to this -->
- Issue #<NUMBER>
- Pull Request #<NUMBER>

### Author Checklist
- [ ] Ensure you provide a [DCO sign-off](https://github.com/probot/dco#how-it-works) for your commits using the `--signoff` option of git commit.
- [ ] Vital features and changes captured in unit and/or integration tests
- [ ] Commits messages follow [AP format](https://github.com/accordproject/techdocs/blob/master/DEVELOPERS.md#commit-message-format)
- [ ] Extend the documentation, if necessary
- [ ] Merging to `master` from `fork:branchname`
- [ ] Manual accessibility test performed
    - [ ] Keyboard-only access, including forms
    - [ ] Contrast at least WCAG Level A
    - [ ] Appropriate labels, alt text, and instructions

When approved and ready to merge, a Pull Request should be squashed down to a single buildable commit and merged into master.

Writing Documentation

The Accord Project repositories use JSDoc for all of its code documentation.

This means that all the docs are stored inline in the source code and so are kept in sync as it changes.

This means that since we generate the documentation from the source code, we can easily provide version-specific documentation by checking out a version of Cicero-UI and running the build.

Development Build for This Repository

Building a Project

To build a project, you clone the source code repository and use npm to build:

# Clone your Github repository:
git clone https://github.com/<GITHUB USERNAME>/techdocs.git

# Go to the directory:
cd techdocs

# Add the main repository as an upstream remote to your repository:
git remote add upstream "https://github.com/accordproject/techdocs.git"

# Go to website directory
cd website

# Install node.js dependencies:
npm install

Running the Project Locally

This project uses Docusaurus to build and manage the public Accord Project documentation website. To run the documentation website on your local machine, first, follow the instructions above to build the project.

# Change to the website directory
cd website

# Start the docusaurus server
npm start

Changes that you make to markdown files in the /docs folder will automatically be reflected in your local running version of the documentation website.

Technical Documentation Specifics

Updating Documentation through Docusaurus

Docusaurus is used for maintaining our documentation. The process for this involves generation of markdown files concerning the API, as well as incrementing the docs version. These two steps are done individually. Updates to the documentation are merged into master, which will generate the new markdown files. Once this is complete, a new pull request should be submitted with the version incremented.

Step 1 - Generating Markdown

Make updates to the source code to improve documentation. Merging this into master will automatically generate Markdown from JSDocs, most notably being the cicero-api.md and ergo-api.md files.

Step 2 - Incrementing Version

Increment the version with the Docusaurus script command through npm.

  npm run version X.X.X

Once this merges into master, the new version number will be recognized and trigger the update and refresh of the Accord Project documentation.

License

Accord Project source code files are made available under the Apache License, Version 2.0.

Accord Project documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0).