So you'd like to contribute some code, report a bug, or request a feature? You're in the right place! This guide covers the basics of starting to contribute to Page Kit.
- Reporting Bugs
- Requesting Features
- Opening a Pull Request
- Code Style
- Testing
- Releasing and versioning
We like it when people report bugs and would definitely rather know about them than be left in the dark. We use GitHub issues for bug tracking. When filing a bug report, there are some guidelines you can follow which will help us quickly resolve your issue:
-
You can do this by searching the repository. This gives us more time to focus on existing bugs, and it might help you find a solution more quickly.
-
It may be that your bug has already been fixed in a newer version.
-
Your bug will generally get fixed much more quickly if you provide clear steps to reproduce the problem. This should include the version numbers of any relevant software.
-
This is not required to file a bug report, but we'll love you if you add one! Writing a failing test or example and opening a pull request will help us quickly locate the issue.
-
If you have multiple different bugs, it's best to open each as a separate GitHub issue.
When making a feature request, it's helpful for us if you follow these guidelines.
-
You can do this by searching the repository. You may find that somebody has already asked for the feature you're thinking of! If this is the case then feel free to join in the comments.
-
If you phrase your feature request as a user need rather than a proposed solution, it opens up more potential for discussion and collaboration – way more fun for everyone.
-
New features should consider the product vision and wider FT technology programme goals. Components and tools within Page Kit should have proven value and defined use-cases applicable to the majority of implementers.
-
If you have multiple different requests, it's best to open each as a separate GitHub issue.
It's important to note that we can't accept every feature request, we'll always discuss why if we're not going to accept them though.
Please do! All of the code in Page Kit is peer-reviewed by members of the FT customer products team. Here are some things you can do to help this review go smoothly:
-
If you're thinking of opening a pull request that adds a feature, you'll save yourself some time and effort if you discuss it in a feature request first or contact the team on Slack (via the
#cp-platforms-teamchannel. The review is guaranteed to go more smoothly if we've chatted about it beforehand. -
The project follows a scheduled release workflow so we encourage the separation of stable, development, and experimental code. See the Git workflow and the release guidelines for more information.
-
The user documentation must be kept up to date with any changes made. Use inline code comments as developer documentation, focusing more on why your code does something than what it's doing.
-
The stability of Page Kit is vital for it to be successful and sustainable. As well as maintaining quality it is important to consider that applications can have very different lifespans; a "quick hack" may remain in production for several months longer than it is required. To reduce churn and make sure Page Kit is stable, hacks, workarounds, and features that are still being tested should live in apps themselves. Page Kit should provide the necessary hooks or slots for apps to insert experimental components; if it doesn't, we can add that. Once features have been proven, and will remain stable, they can graduate to Page Kit itself.
-
This is a collaborative project and sometimes your pull request may not work in the best interests of those in another team so they have been given the power to say "no". If your pull request is good but would require a major release then it may be held until a more suitable time.
-
We have a code style, and the pull request build will fail if this isn't followed. If the code style varies for a project already then it's best to follow the example set in that project. We're not mean, we just like consistency!
-
When fixing a bug, reference the original report; when adding a feature, link to the original feature request. It'll help us massively!
The best way to ensure you stick to the Page Kit code style is to make your work consistent with the code around it. We also provide a Prettier configuration to automatically format files and run ESLint before any tests so don't let it get in the way of your flow – you can fix it afterwards!
- 2 spaces for indentation
- 100 characters per line
- Avoid abbreviating names (e.g.
requestis better thanreq)
- No semicolons
- Use
', not" - Use ES2018 where available
- Commas at the end of the line, not the start
- Add two empty lines above a
h2(to break up sections) - Indent lists and quotes (by two spaces)
- Use reference-style links as much as possible
We use Jest as the test runner and assertion library for all code. To run tests for all packages in the repository use the command npm test or to run tests only for an individual package the command is npm test -- --testPathPattern <package name>.
The applications in the examples/ folder are all used as integration tests which are always run on CI. You can run the integration tests locally using the npm test:examples command. Integration tests may use Supertest or Puppeteer.
Code style is enforced with Prettier and non-compliant code should be automatically formatted when committing.
We have implemented ESLint to statically analyse code for problems.
Please refer to the release guidelines.