We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
- Reporting a bug
- Discussing the current state of the code
- Submitting a fix
- Proposing new features
- Becoming a maintainer
As you will read on the details of contributing, remember that when unsure about something, e.g. formatting or level of detail, err on the side of submitting those items. The formatting or details can always be filled in later, but your insight cannot be replaced.
- Reporting Small Bugs, Quick Fixes, Typos
- Reporting Bugs
- Reporting Security Issues
- Suggesting a Feature or Enhancement
- Contribution Guidelines
- Pull Requests
- Code Review Process
- Your First Contribution
- License
- References
In these cases, you can either report it as a bug, or create a pull request right away, as the changes are likely to be accepted.
These are the bugs/fixes that do not introduce any new functionality or logic, as long as the change does not affect functionality. Some examples are:
- Spelling / grammar fixes
- Typo correction, white space and formatting changes
- Comment clean up
- Bug fixes that change default return values or or constants
- Adding logging messages or debugging output
- Changes to ‘metadata’ files like .gitignore, build scripts, etc.
- Moving source files from one directory or package to another
Report bugs using Github's issues
Issues are very valuable to this project:
- Ideas are a valuable source of contributions others can make
- Problems show where this project is lacking
- With a question you show where contributors can improve the user experience
Thank you for creating them ❤️
The single most important thing is to report the bug. If you are unsure about some details or the format of the report, create an issue and write what you know!
Once that is done, there will be plenty of opportunities to refine the issue to ensure we all understand the topic clearly.
Generally, write bug reports with detail, background, and sample code. This is a good example of a bug report.
Great Bug Reports tend to have:
- A quick summary and/or background.
- Steps to reproduce.
- Be specific!
- Give sample code if you can.
- What you expected would happen.
- What actually happens.
- Notes, possibly including why you think this might be happening, or stuff you tried that didn't work.
Thorough bug reports help tremendously in getting the ideas across.
If you find a security vulnerability, email juraj.oravec.josefson@gmail.com. Do not open an issue as publicizing the security vulnerability may put more people/data at risk.
Not sure if you came across a security issue? Ask yourself these two questions:
- Can I access something that's not mine, or something I shouldn't have access to?
- Can I disable something for other people?
If the answers are yes, or you are not sure, it's safer to get in touch.
When reporting the security issue, follow the same general rules as when writing a bug report. Share the details and be specific.
Is our project missing something? Maybe a new feature, support for a particular standard (think YAML vs JSON), or maybe documentation?
Whichever the area, if you think our porject should or could expand, share it with the rest of the community!
To suggest a feature, open a new issue and select the Feature request template. The template will guide you through what information is needed to be able to fairly evaluate the feature request.
Don't worry if you aren't sure about some of the details mentioned in the Feature request template! Fill in what you know, and if the suggestions is suitable to the project, we will guide you on the rest of the information needed.
After the feature request is submitted, congratulations! Now be sure to check out notifications on the issue and respond to questions or requests of more information from the rest of the community.
Once all necessary information is know, the feature request is formalized so it could be considered by the project's core team. You can see the state of the suggestion throughout our pipeline by following the suggestion through our issue labelling conventions.
Thank you for taking the time to read these guidelines. The aim of these guidelines is to ensure the time of contributors and maintainers is used as effectively as possible, so we all get more enjoyment from driving the project forward.
This section goes more in-depth of how things work, so buckle up!
We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
We use Github Flow.
For more details on the workflow we use and integrations that help us with that see the page on Source Version Control and Workflow.
Pull requests are the best way to propose changes to the codebase. All code changes should happen through them.
We actively welcome your pull requests:
- Fork the repo and create your branch from
master. - If you've added code that should be tested, add tests.
- If you've changed APIs, update the documentation.
- Ensure the test suite passes.
- Make sure your code lints.
- Issue that pull request!
See our logging strategy and the tools we use here.
Commit messages are covered in Source Version Control and Workflow.
Label conventions are covered in Labelling Convention and Issue Pipeline.
For the styling details, see .eslintrc.js and .prettierrc (JS/TS files),
.pug-lintrc.js (PUG files), stylelintrc.yml ((S)CSS files).
As a rule of thumb:
- 2 spaces for indentation rather than tabs
- 80 character line length
- Run
npm run lintto fix the style
Keeping a healthy community that is welcoming to newcomers and encourages new contributors from different walks of life is paramount to us. If you haven't done so yet, be sure to check out our Code of Conduct.
Always create issues for any notable changes and enhancements that you wish to make. Discuss things transparently and get community feedback.
At times, we may ask you to provide additional information in issues or pull requests, or ask you to make changes to your contributions to ensure that your contribution fits in well with the rest of the code.
We do this as we strive for the balance of keeping the project as accessible as possible while making sure it's still progressing in the agreed-upon direction.
To guard for quality, follow our checklists when submitting pull requests. Your submissions may also be blocked by bot checks. In those cases we again ask you to refine the contribution to pass those checks.
We have an open mind! Whether it's writing code, writing blogs, improving documentation, bug triaging, or writing tutorials are all examples of helpful contributions that mean less work for others.
And it doesn't have to stop there! Do you know of somebody who may benefit from our project? Or you want to mention us at your next conference? Suggestions for improving UX? The ways to help are truly endless!
AllContributors, has a list of pretty much every way how you can contribute.
We use AllContributors, to recognize the work of everyone who has contributed. Once you have contributed, we'd love to show the world that you are among our contributors.
For that we use the AllContributors Bot. To add you to the contributors, make a comment on an issue or a PR with text:
@all-contributors please add <your username> for <contributions>where <contributions> is any of the emoji keys.
If the contributor doesn't add themselves, other community members might suggest to add them to recognize their contributions.
However not everybody might want to agree to it. We want to respect people's preferences, so if you want to add somebody, please first create an issue or a PR, mention the user there, and give them the chance to discuss it.
Please see and use the available pull request template.
To use the pull request template in GitHub, simply create a new pull request, and the template will be automatically loaded. See GitHub's wiki for more details.
The template will guide you through the process of writing a pull request that contains all the information.
In short, the template ensure that each pull request:
It should be clear which problem you're trying to solve with your contribution.
For example:
Add link to code of conduct in README.md
Doesn't say anything about why you're doing that.
Add link to code of conduct in README.md because users don't always look in the CONTRIBUTING.md
Mentions the problem that you have found, and the pull request shows the action you have taken to solve it.
Always include the reference to the issue that the pull request relates to. If
there is no issue, keep them no-issue.
The checklist in the pull request template serves as a reminder to keep the code quality high by including tests, linting or updating docs or metadata.
By having a standard way to present the pull requests, we can get accustomed to that and learn to navigate them faster.
If you would need help with english language contributions, have a look at Grammarly or Hemingway App
This repository has a code of conduct which should be followed.
The code review process is formalized in .zappr.yml.
Zappr is a GitHub bot which checks
(among other), whether the required users or any members of certain groups have
reviewed the pull request.
The maintainers aim to review the pull requests on a regular basis (every or every other week) and in response expect a reply within 2 weeks if any issues were raised.
Unsure where to begin contributing? You can start by looking through issues tagged with help wanted label.
Here is a couple of friendly tutorials:
In short, when you submit code changes, your submissions are understood to be under the same MIT License that covers the project. Feel free to contact the maintainers if that's a concern.
This document was created adapting the great guidance and ideas from Brian A. Danielak's (briandk) template, Billie Thompson's (PurpleBooth) template and Nadia Eghbal's (nayafia) template
In addition (or in some cases because of taking inspiration from the above), this document was adapted from the open-source contribution guidelines for dwyl, Facebook's Draft, Elasticsearch, React, and Chef.
Table of contents generated with markdown-toc.