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 x-dash.
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.
-
It's imperative that the components we build and maintain as a part of
x-dashwork well for both App users and FT.com users whether on their phone or desktop PC. Features which lack a suitable experience for the big or small screen are more likely to be rejected. -
New features should consider the product vision and wider FT technology programme goals. All components and tools within
x-dashmust 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 x-dash is peer-reviewed by members of The App and FT.com teams. 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. 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 should 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.
-
When adding new variations or configurations to an existing component these should be made visible by adding a new story for inclusion in the component demos. These demos also generate the snapshots used for testing and your build will fail if do not update these.
-
The stability of
x-dashis vital for it to be successful. As well as maintaining quality it is important to consider that The App and FT.com have very different lifespans; a "quick hack" may remain installed on an App user's device for several weeks or even months. Need a hack? Keep it in your app! -
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!
This project follows a workflow designed around project releases. It is less strict than Gitflow but we encourage the separation of stable, development, and experimental branches in order to follow a scheduled release cycle.
- The
mainbranch is for the current stable release. Bugfixes are merged into this branch. - The
developmentbranch is for upcoming major or minor releases. This branch tracksmainand new features are merged into it. - Branches for new features should track and raise pull requests against the
developmentbranch ormainbranch if there are not any upcoming releases planned.
The best way to ensure you stick to the x-dash 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!
- Tabs for indentation (except in
package.jsonand Markdown files) - 100 characters per line
- Don't abbreviate names (
requestis better thanreq)
- Use semicolons
- Use
', not" - Use ES6 where available
- Commas at the end of the line, not the start
- Use BEM-style naming for classes
- One selector per line
- One property/value per line
- Don't style IDs
- 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 for testing x-dash components and packages. Most commonly this takes the form of snapshots generated from the stories associated with a component. We enforce code quality with ESLint. To learn more about testing components see the testing components documentation.