Skip to content

Latest commit

 

History

History
217 lines (139 loc) · 9.62 KB

CONTRIBUTING.md

File metadata and controls

217 lines (139 loc) · 9.62 KB
Raw

Contributing to the Intelligence Community Design System guidance site

Welcome and thank you for contributing to the Intelligence Community Design System guidance site. This guide will take you through the technical considerations for contributing.

Table of contents

Code of conduct

The Intelligence Community Design System (ICDS) has adopted the Contributor Covenant. Please familiarise yourself with our full conduct principles.

How to contribute

To find out more about the different types of contributions, the criteria or our roadmap, read how to contribute to the Design System and UI Kit.

Making a suggestion or raising a bug

You can help us speed up the development of our Design System by contributing new guidance, improving existing guidance or raising bugs.

Before getting started, please check our Github issues page to check whether a similar bug or suggestion already exists. If not, create a ticket with as much information as possible. The working group will triage your ticket and get back to you. The working group meet on a fortnightly basis to review new tickets, but important bugs will be reviewed sooner.

Contributing code

Gatsby is the React based framework used to build the guidance site with the content pages built in MDX. All content pages can be found in ./src/content/.

Setting up the Design System guidance site codebase

Node 16+ is required to build and run the codebase.

If you would like to contribute code, please complete the following steps:

  1. Fork the Design System guidance site repository and clone your forked repo onto your device.
  2. Make sure to add the mi6/ic-design-system repo as your upstream remote branch, by running:
git remote add upstream git@github.com:mi6/ic-design-system.git
  1. Create a new branch in your forked repo, named after the issue number of your contribution (e.g. feature/123-new-feature).
  2. Run the following:

NPM

npm install
npm start

Yarn

rm package-lock.json
yarn install
yarn run start

  1. Make your changes, keeping to the coding standards and practices.

  2. Commit your changes, as per the Git commit style guide and push to your branch.

  3. Submit a pull request to merge to the develop branch in the original repository:

    • Click on Compare & pull request.
    • Set the base to be the original repository's develop branch and the host to be your forked branch.
    • Click on Create pull request.

Pull Requests

All changes will be reviewed via a pull request. Raise the pull request to merge to the develop branch. Provide details on what has been changed or added. To make sure there is enough detail in the pull request, our pull request template is available.

All pull requests will be reviewed by:

  • Checking the change meets the guidance set out on this page.
  • Checking the change meets the requirements of the ticket.
  • For new components or large changes, testing the project locally by importing the component into a real project.
  • Checking anything else deemed relevant by the reviewer.

Pull requests must have the approval of 2 reviewers before they can be merged into the develop branch.

Coding standards and practices

Accessibility

All changes must meet the criteria for WCAG 2.2 AA. Find out more about the importance of accessibility.

Style guide

Linting tools are ran against the codebase to keep in line with our coding standards. The linting tools used are:

These tools are ran as part of the pre-commit and can also be ran separately.

Resolve linting and formatting issues via npm run lint:fix and npm run prettier:fix.

Git user configuration

As a data protection measure, this repository enforces the use of GitHub user email address in your commit. Please follow these steps:

  1. Visit your GitHub email settings
    • Optionally check the settings "Keep my email addresses private" and "Block command line pushes that expose my email"
  2. On this page, under Primary Email Address you'll see a user email that follows the pattern <username>@users.noreply.github.com.
  3. Inside your developer environment, open a command line in the directory of the ic-ui-kit repository
  4. Enter the command git config user.email <EMAIL> where you replace <EMAIL> with the address from step 3. This will be applied to commits made in this repository.

Git commit

For automated versioning, we use Conventional Commits.

To make it easy to use we have implemented Commitizen.

Please ensure that your commits are signed when contributing to the Design System guidance site repository.

Follow these steps when making a commit:

  1. Ensure your commit only contains changes for one of the scopes. If your change affects more than one scope then make multiple commits, i.e. one for each scope.

  2. Once your changes are staged, run git commit. This will trigger the Commitizen command line utility.

  3. Select the commit type, read each of the options and select the appropriate one.

  4. When asked for scope, enter either:

    • root if your commit contains changes to the root of the project.
    • docs for a documentation changes.

  5. Provide a short description of the change.

    • Use the present tense, such as "Add feature" not "Added feature"
    • Reference the issue number at the start of the commit, such as "#123 Add feature"

  6. Provide a longer description of the change.

  7. If there are breaking changes enter y and provide a description.

  8. Provide a link to the issue by entering the reference e.g. #123.

  9. When the editor opens up, check your commit message and press Ctrl+x to confirm.

Amending a commit

If you need to make changes to a commit (for example, after receiving comments on a PR), follow these steps:

  1. If you're amending the most recent commit:

    • Stage your changes using git add and include the files you want to update.
    • Run git commit --amend --no-edit to amend the most recent commit without changing the commit message.
    • The Commitizen prompt will still appear as if you are making a new commit. Exit the prompt (usually by pressing Ctrl+C).
    • Push the changes to the remote repository using: git push --force.

  2. If you're amending an older commit:

    • Use git rebase to modify an older commit. For example, to modify commit a1312407, run:

      git rebase --interactive a1312407

    • In the default editor, change pick to edit for the line mentioning a1312407.

    • Save the file and exit. Git will interpret and automatically execute the commands in the file, placing you in the state just after creating commit a1312407.

    • Amend the commit by making your changes and then running:

      git commit --all --amend --no-edit

    • The Commitizen prompt will still appear as if you are making a new commit. Exit the prompt (usually by pressing Ctrl+C).

    • Continue the rebase process by running:

      git rebase --continue

    • Push the changes to the remote repository using:

      git push --force

Styling

Testing

Tests should be sufficient enough for the functionality changed or added.

Testing should always include accessibility testing. Please read our advice on how to test for accessibility

Useful links