Skip to content

Latest commit

 

History

History
118 lines (71 loc) · 6.27 KB

CONTRIBUTING.md

File metadata and controls

118 lines (71 loc) · 6.27 KB
Raw

Contributing

Running the project locally

govuk-react is a monorepo using yarn workspaces.

This is so that components can be published independently and applications can require different versions of a component if a breaking change is introduced in a version of a specific component. We are loosely following the structure that Jest uses.

As such, the build process for development is slightly more involved than an npm install:

  1. Install npm 7.7 or later for workspaces support.

  2. Install dependencies, link packages, compile and start storybook:

yarn
yarn build
yarn start

Creating a new component

To create a new component:

  • yarn create-component -- my-new-component where my-new-component is the name of your new component.

This creates a folder named my-new-component in src/components with the component file (index.js), a basic render test (test.js), and a default story (stories.js). You will need to add this to src/stories/index.js to view it in storybook.

Unit testing

To run unit & eslint tests:

yarn test

To run & watch unit tests:

yarn test:unit

Generating docs

Markdown docs, in README.md files, are automatically generated based on the React component APIs. When making changes to component APIs, you should regenerate the docs to keep them in sync with the components.

To generate docs:

yarn docs

Opening a pull request

  • when adding a new component, include a screenshot of the component in the PR
  • when adding new components, try to keep 1 component per PR, unless there are unavoidable interdependencies
  • when fixing a visual issue, include a unit test or snapshot test that proves the issue, and include a screenshot of the component before and after in the PR
  • when fixing a functional issue, include a unit test that proves the issue (fails before PR is merged and succeeds after)

Releasing

In order to prepare a release:

  • ensure you have gh cli installed (e.g. brew install gh)
  • run ./scripts/release.sh, followed by a semver increment e.g. ./scripts/release.sh patch (if this is the first time running gh, you will be asked for your GitHub credentials).
  • this will open a PR on GitHub and draft a release
  • Edit the PR and write the release notes in the PR description (see release notes below)
  • get approval for the PR (reviewers should be reviewing the release notes in the PR description) then merge the PR
  • once the PR is merged, open the draft release corresponding to the new version number on GitHub, change the target branch to master, check the title and description and then click Publish release.

When the tag is created, the CI server will automatically release to npm.

Release notes

Please refer to the commit history in GitHub since the last release. These can be copied directly and then categorised.

Please list in this order, using ## for headings:

  • Breaking changes or anything or similar significance
  • Enhancements
  • Bug fixes
  • Documentation

Changes that have no user facing changes, such as our Github workflows, do not need to be included.

Please look at previous releases for examples.

Conventions

The following conventions are planned but not fully implemented. We should be consistent on these before releasing version 1. At the point where the library is consistent, the conventions should be moved to README.md rather than CONTRIBUTING.md.

Fields vs. Inputs

For the purpose of this project:

  • A field is the combination of a label, input(s) and validation/error messages. The Field components used by this project should follow the prop structure of Final Form and Redux Form fields, in that they accept an input prop and a meta prop.
  • An input is just the form control that the user enters data in to, without a label or error/validation message. Inputs are normally associated with a Field and should be used on their own by importing the Field then using <FieldName.Input />. Inputs follow the prop structure of Final Form and Redux Form inputs.

More details in issues/164

Anchors

We want to be router agnostic. We want to support parent projects using React Router or Reach Router, without introducing either as a dependency of this project. As such we provide an as prop on components that we expect can be used as React Router Links or NavLinks.

White Space

Historically components were build to have no white space around them. They were then wrapped with the withWhiteSpace HOC to set the default spacing below the component and also provide support for an mb prop to allow the parent application to override this spacing.

We have found that the use of the withWhiteSpace HOC can be problematic when it comes to applying complex styling rules involving descendent selectors, and thus it's use is now deprecated. Instead equivalent and enhanced facilities have been added to the spacing library in @govuk-react/lib.

At the time of writing we are at the beginning of the process of transitioning to this new spacing method.

Components are built to have white space around them to match their equivalents in govuk-frontend. To assist with this, styling utility function are provided in the spacing library in @govuk-react/lib. Typically a component will use the withWhiteSpace function within a component to generate a styling function to apply to a styled component.

The withWhiteSpace function accepts default values for both padding and margin, and also provides support for overriding those defaults with equivalently named props. Spacing styles created are responsive and adjust for mobile/tablet sizes. For backward compatibility with the withWhiteSpace HOC it also supports a marginBottom config and mb prop.

More details in issues/173 and pull/523