First off, thank you for considering contributing to FreeFrom Compensation API. It's people like you that make FreeFrom Compensation API such a great tool.
Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
FreeFrom Compensation API is an open source project and we love to receive contributions from our community — you! There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into FreeFrom Compensation API itself.
- We pledge to make participation in our projects and community a harrasment-free experience for everyone. Please read and adhere to Ragtag's Code of Conduct when interacting with others on this project. Please report unacceptable behavior to coc@ragtag.org.
- We follow the Rails Style Guide. Please read the sections that are relevant to the parts of the code to which you're contributing (i.e. routing, controllers, etc.)
- We require that all code be formatted by Prettier where applicable. We use the default settings for each language.
- Create issues for any major changes and enhancements that you wish to make. Discuss things transparently and get community feedback.
- All changes should be made through by pull requests. Pull requests will be reviewed by one or more of FreeFrom Compensation API's maintainers. Once approved, it is the responsibility of the owner of the pull request to merge the changes to the master/main branch.
This section guides you through submitting a bug report for FreeFrom Compensation API. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
If you find a security vulnerability, do NOT open an issue. Email security@ragtag.org instead.
- Perform a cursory search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one. If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
Bugs are tracked as GitHub issues.
Explain the problem and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible. When listing steps, don't just say what you did, but explain how you did it. For example, if you moved submitted a form, explain if you clicked the form's submit button or pressed enter inside one of the inputs?
- Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Explain which behavior you expected to see instead and why.
- Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
- If the problem is related to performance or memory, include a CPU profile capture with your report.
- If the problem wasn't triggered by a specific action, describe what you were doing before the problem happened and share more information using the guidelines below.
Provide more context by answering these questions:
- Did the problem start happening recently (e.g. after updating to a new version of FreeFrom Compensation API) or was this always a problem?
- If the problem started happening recently, can you reproduce the problem in an older version of FreeFrom Compensation API? What's the most recent version in which the problem doesn't happen?
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
Include details about your configuration and environment:
- Which version of FreeFrom Compensation API are you using? If you're using FreeFrom Compensation API on the web, let us know what dates you experienced the issue on.
- What's the name and version of the operating system you're using?
- What's the name and version of the browser you're using?
This section guides you through submitting an enhancement suggestion for FreeFrom Compensation API, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
Before creating enhancement suggestions, please check this list as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible.
- Perform a cursory search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
Enhancement suggestions are tracked as GitHub issues and should provide the following information:
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a step-by-step description of the suggested enhancement in as many details as possible.
- Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, using Markdown code blocks.
- Describe the current behavior and explain which behavior you expected to see instead and why.
- Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate where the suggestion is expected to go. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
- Which version of FreeFrom Compensation API are you using? If you're using FreeFrom Compensation API on the web, let us know what dates you experienced the issue on.
- What's the name and version of the operating system you're using?
- What's the name and version of the browser you're using?
Unsure where to begin contributing to FreeFrom Compensation API? You can start by looking through these good first issue and help wanted issues:
- Good first issues - issues which should only require a few lines of code, and a test or two.
- [Help wanted issues](https://github.com/ragtagopen/freefrom-compensation-api/issues?q=is%3Aopen+is%3Aissue+label%3A"help wanted"+sort%3Acomments-desc) - issues which should be a bit more involved than beginner issues.
Both issue lists are sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
Working on your first Pull Request? You can learn how from this free series, How to Contribute to an Open Source Project on GitHub.
At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first.
- Apply to be a Ragtag volunteer at https://ragtag.org/join.
- Get added as a contributor to the project by asking in the Slack room for Project Name.
- Create a new branch in your local copy of the project
- If this is your first time contributing to Project Name, add your name to the CONTRIBUTORS file and include that change in your pull request.
- If you like the change and think the project could use it:
- Be sure you have followed the code style
- Make sure your work passes all existing tests
- Open a pull request with your changes
- Project Name's maintainers may have questions or suggestions for your work, please respond as soon as you can
- If you want feedback while you're working on your changes, you can open your pull request early in the process and start the title with
[WIP]for Work in Progress. Then ask other contributors to review your work and ask any questions you have about what you're working on.
Tests for this repo are written using the rspec-rails gem. To write tests for a new file, or contribute tests to an existing file, find the corresponding test file in the spec folder (for example, if you create a file with the path app/models/foo.rb, create a spec file at spec/models/foo.rb).
To run all tests in this project, run the command bundle exec rspec. To run tests from a specific file, include the path to the file (e.g. bundle exec rspec spec/models/foo.rb). To run a specific test, include a colon and a line number (e.g. bundle exec rspec spec/models/foo.rb:25).
We follow the Standard Issue Labels for our projects. Additionally, all pull requests that add new features should have their titles start with FEATURE. Finally, if your pull request fixes one or more issues, please note that in your pull request body or the body of your commit messages using one of the supported keywords.
Portions of this document come from https://github.com/nayafia/contributing-template/blob/master/CONTRIBUTING-template.md and https://github.com/atom/atom/blob/master/CONTRIBUTING.md.