Contributing
In the first place, thank you for your interest in contributing! 🙏
Development
Working on the site requires:
This allows running the documentation site which serves as a development platform.
Configure Docker Compose
Review the default env variable values in the docker-compose.yml
file.
The defaults should work for most systems, but can be changed if needed.
To change them, edit the .env
file as needed.
Use Docker Compose
Node shell
All npm commands such as npm ci
, npm test
, npm run eslint
and others you
need to run them within the node_shell
docker container.
To log into the container, run:
docker compose run --rm node_shell
Run the Dev Server
-
Within
node_shell
: Install dependencies:npm ci
-
On host: Run development server:
docker compose up node_dev_server mkdocs_dev_server
Build the Project
-
On host: Make sure the dev server is not running:
docker compose down
-
Within
node_shell
: Install dependencies:npm ci
-
On host: Build JS:
docker compose run --rm node_build_site
-
On host: Build mkDocs:
docker compose run --rm mkdocs_build_site
Git Workflow
In order for the automation to work in the best possible way (we use GitHub Actions), please follow these guidelines:
-
One pull request per subject. Don't combine unrelated changes in a single PR unless they are really subtle details such as fix of a typo.
-
Only PRs into
master
branch are listed in changelog. PRs into other branches are not picked up by release automation. -
Name your branches according to nature of change. Choose one of:
bc/*
for breaking changesfeature/*
for featuresbugfix/*
for bugfixesrefactoring/*
for refactoring of the librarydocs/*
ordocumentation/*
for changes in docsmaintenance/*
for maintenance (builds, dependencies, automation, etc.)release/*
for releases (administrators only)
-
Write clear, helpful and descriptive commit messages.
- Use imperative and write in English, e.g. Update dependencies or Claim support for controlled components only.
- If an issue exists for your changes, append the issue number in parentheses to the end of the commit message, e.g. Update dependencies (#261).
- Optionally use Markdown code blocks to emphasize, e.g.
Create
ScrollView
component (#53).
-
Write clear, helpful and descriptive PR names.
- All rules for commit messages apply also for PR names.
- Always check that PR name meets the requirements above because PR names are used in changelog. GitHub automatically truncates long PR names and picks up branch name for multi-commit PRs, so it's necessary to make sure the PR name is what we want to have in the changelog.
- If an issue exists for your changes, append this text to PR
description (the topmost comment in the PR) in order for the issue
to be
closed automatically once the PR is merged:
Closes #<ISSUE NUMBER>
. You will know the issue is linked correctly when it appears in the Linked issues section of the PR. (Having the issue mentioned in commit message and/or PR name does not have this effect.) - If there is no issue for your changes, please add your PR to
The Board
GitHub project in the Projects section of the PR. The correct board column will be selected automatically. This helps us keep track of what is in development.
Pull requests are labelled automatically. You can add more labels to better
qualify the nature of the change — in such case, it will be included in all
corresponding changelog groups. Or use the skip changelog
label to exclude a
pull request from the changelog.
Package Linking
The best way for development of React UI is to link react-ui
into your
application with npm link
so you can see it in action.
- In React UI repository, run
npm link
- In your application, run
npm link @react-ui-org/react-ui
To prevent Invalid Hook Call Warning when React UI is linked, add the following code to your app's Webpack config:
const path = require('path');
module.exports = {
resolve: {
alias: {
react: path.resolve('./node_modules/react'),
'react-dom': path.resolve('./node_modules/react-dom'),
},
},
};
General Guidelines
To keep React UI consistent and predictable the following guidelines should be observed:
- If component accepts the
children
prop it should be either required or the element should returnnull
when no children are provided. - When forwarding HTML attributes to the component the following rules should
be observed:
- If the component internally instantiates one or more interactive (clickable/editable) elements, the attributes should be forwarded to all of them.
- If the component does not internally instantiate an interactive (clickable/editable) element, the attributes should be forwarded to the root element of the component.
Documenting
We use combination of Material for MkDocs and Docoff as the documentation platform.
Do see their respective documentation for details.