Skip to content

Latest commit

 

History

History
139 lines (86 loc) · 7.7 KB

contribution.md

File metadata and controls

139 lines (86 loc) · 7.7 KB

Contribution

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.

Reporting bugs

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:

  • Check if the bug has already been reported

    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.

  • Make sure your software is up to date

    It may be that your bug has already been fixed in a newer version.

  • Provide steps to reproduce

    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.

  • Write a failing test or example

    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.

  • Open multiple bug reports

    If you have multiple different bugs, it's best to open each as a separate GitHub issue.

Requesting features

When making a feature request, it's helpful for us if you follow these guidelines.

  • Check if the feature has already been requested

    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.

  • Phrase as user needs

    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.

  • Consider big and small screens

    It's imperative that the components we build and maintain as a part of x-dash work 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.

  • Does it have proven value?

    New features should consider the product vision and wider FT technology programme goals. All components and tools within x-dash must have proven value and defined use-cases applicable to the majority of implementers.

  • Open multiple feature requests

    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.

Opening a pull request

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:

  • Discuss features first

    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.

  • Check the workflow and release guidelines

    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.

  • Update the documentation

    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.

  • Update affected stories and snapshots

    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.

  • No hacks, experiments or temporary workarounds

    The stability of x-dash is 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!

  • Reviewers are empowered to say no

    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.

  • Follow the code style

    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!

  • Reference other issues

    When fixing a bug, reference the original report; when adding a feature, link to the original feature request. It'll help us massively!

Git workflow

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 main branch is for the current stable release. Bugfixes are merged into this branch.
  • The development branch is for upcoming major or minor releases. This branch tracks main and new features are merged into it.
  • Branches for new features should track and raise pull requests against the development branch or main branch if there are not any upcoming releases planned.

Code style

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!

General style

  • Tabs for indentation (except in package.json and Markdown files)
  • 100 characters per line
  • Don't abbreviate names (request is better than req)

JavaScript style

  • Use semicolons
  • Use ', not "
  • Use ES6 where available
  • Commas at the end of the line, not the start

CSS/Sass style

  • Use BEM-style naming for classes
  • One selector per line
  • One property/value per line
  • Don't style IDs

Markdown style

  • 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

Testing

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.