Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
145 lines (98 loc) · 7.27 KB

CONTRIBUTING.md

File metadata and controls

145 lines (98 loc) · 7.27 KB
Raw

Contributing

Requirements

Tip

nvm can be used to install and manage multiple versions of Node.js.

Setup

  1. Clone the repository

  2. Install project dependencies

    npm install

  3. (Optional) Configure your IDE to automatically format code with Prettier. If you do not do this, you can run the formatter manually before pushing changes:

    npm run format

Repository structure

The source code for the web components is located in the packages/web-components workspace.

The documentation website is located in the website workspace.

Making changes

Web Components

The development server can be started by running:

npm run start:web-components

By default, this will start a server on http://localhost:3333. From the index page you can navigate to a subpage for the component you are working on. The server will watch for changes to the source files and automatically reload the browser when changes are made.

When updating existing components, it is recommended to add to or update the examples in HTML file(s) alongside the component source code in order to exercise your changes. This will allow you to see the changes in the browser as you work.

To create a new component, create a new directory in packages/web-components/src/components with the component name. Within that directory, add a tsx file which defines the components itself. Also add an index.html file which demonstrates the component usage. Add a link to this HTML file in the top-level packages/web-components/index.html file. If necessary, add a CSS or SCSS file to the component directory.

Important

Each .tsx file must only define a single component.

Important

Use standard naming conventions. Files and folders should be the name of the component without the go- prefix, e.g. my-component.tsx, my-component.scss. The tag name for the component should be prefixed with go-, e.g. go-my-component.

src/
  components/
    my-component/
      my-component.tsx    # Component source code, defining `tag: 'go-my-component'`
      my-component.scss   # Component styles
      index.html          # Component usage example

A readme.md file will be automatically generated in the website workspace the next time the project is built. This file does not need to be created or edited manually, but it should be committed with your changes.

npm run build

Documentation

Start the documentation development server by running:

npm run start:docs

This will start a server on http://localhost:3000 where you can view the documentation website. The server will watch for changes to the website source files and automatically reload the browser when changes are made.

"Module not found" error? If you see an error like this: 
Module not found: Error: Can't resolve '@geneontology/web-components'

It is probably because the @geneontology/web-components package is not built yet. Run the following command to build the package:

npm run build:web-components

The individual component documentation pages (in website/docs/components) are generated by Stencil. Do not hand-edit these files. Instead, update the component source code and regenerate the readme.md files with:

npm run build --workspace=packages/web-components

For more information on how Stencil translates component source code into documentation, see the Stencil documentation.

Testing

To run the test suite, use the following command:

npm test

See the Stencil documentation for more information on writing unit tests for Stencil components.

Contributing changes

Before opening a pull request, ensure that the following steps have been taken:

  • Format code with Prettier (npm run format).
  • Address any linting errors (npm run lint).
  • Ensure all tests pass (npm test).
  • Regenerate any automatically generated files (npm run build). Commit these changes along with your source changes.

Publishing a new version

A new version of this package can be published to NPM via GitHub Actions.

  1. Ensure all changes have been tested and merged into the main branch.
  2. Go to the Publish package workflow page.
  3. Click the "Run workflow" dropdown.
  4. Note the current version number (in package.json) and select the appropriate Release Type which will determine the new version number.
Release Type Description Examples (current version → new version)
patch Bug fixes, no new features 1.2.3 → 1.2.4
1.2.4-beta.3 → 1.2.4
minor New features, no breaking changes 1.2.3 → 1.3.0
1.3.0-beta.3 → 1.3.0
major Breaking changes 1.2.3 → 2.0.0
2.0.0-beta.3 → 2.0.0
prepatch Pre-release of a patch version 1.2.3 → 1.2.4-beta.0
preminor Pre-release of a minor version 1.2.3 → 1.3.0-beta.0
premajor Pre-release of a major version 1.2.3 → 2.0.0-beta.0
prerelease Increment the pre-release number without changing the version, if the current version is a pre-release. Otherwise, works the same as prepatch. 1.2.3-beta.2 → 1.2.3-beta.3
1.2.3 → 1.2.4-beta.0
  1. Click the green "Run workflow" button.
  2. Verify that the workflow completes successfully and that the new version is available on NPM.
  3. If this release has publicly relevant changes, make an announcement on https://github.com/geneontology/go-technical-announcements/issues ("Widget library release" template).
  4. If this release has internally relevant changes, make a tracking issue in this repo to coordinate/track the rollout ("New release TODO").