7.8 KiB
Contributing Guidelines
Thanks for taking the time to contribute! We would like the Astuto community to be a welcoming environment for both seasoned programmers and absolute beginners. The following guidelines should help you get started regardless of your skill level.
How to contribute
There are various ways to contribute to Astuto. In this section we list the most common ones.
Reporting bugs
Open a new issue on GitHub. In doing so, please follow these guidelines:
- Check whether this bug has been reported before in the issues panel. If that's the case, consider posting a comment to that already open issue, or react to a comment you agree with (for example, with the 👍 emoji). Otherwise, open a new issue.
- Choose a short, meaningful title
- Start the issue description with a quick summary of the problem you encountered
- Include steps to reproduce the issue
- State how you expected the program to behave, and how it actually behaved
- If applicable, write down stuff you tried to solve the problem that didn't work
- Feel free to include personal thoughts about why you think this issue is occurring
Proposing features
As for bug reports, we use GitHub issues to track feature requests. So, if you want to propose a feature or enhancement, just open a new issue. As always, check whether that feature has already been proposed before posting. If the issue is already there, just comment or add a reaction to express that you'd like this feature too.
Coding
In order to contribute code, you should use the usual GitHub fork workflow. See this section if you aren't comfortable with it yet.
The following is a list of some guidelines to take into consideration when contributing code:
- If you're going to fix a bug or implement a feature that has already been documented with an issue, please let the community know by posting a comment on that issue. In this way, we avoid the (unfortunate) possibility of two people working on the same thing at the same time.
- If you want to fix a bug or implement a new feature that hasn't already been documented with an issue, please open an issue before.
- Follow styleguides for both commit messages and code
- When you're done, open a pull request and explain clearly what it is about. We also encourage you to link to the issue it fixes.
Getting involved in the community
We'd love to hear your opinion both on small feature additions and on long-term strategic discussions. Indeed, you can contribute to Astuto just by dropping a comment to let us know your point of view.
In particular, some issues and pull requests are labeled "discussion". That label signifies that further discussion is required to move forward the development process: thus, we encourage you to express your opinion especially on these topics.
Styleguides
Git commit messages
Short summary of the commit
More throughout explaination of what the commit does and the reasoning behind it (optional)
For commit messages, please follow these broad guidelines:
- Separate subject from body with a blank line
- The subject must use present tense ("Add feature" not "Added feature") and imperative mood ("Fix bug" not "Fixes bug")
- Limit the subject to about 72 characters
- Try to be both coincise and clear
Coding conventions
General coding conventions
- Write clean code
- We strongly encourage to write specs associated to the feature you're adding
Ruby coding conventions
TODO
JavaScript coding conventions
TODO
This is my first contribution! Help!!
First off, we want to clarify that you don't need to be an expert or anything like that to contribute. There are various ways in which you can contribute and we appreciate all kind contributions: huge ones as well as small ones, code contributions as well as documentation contributions.
Moreover, we understand that contributing to open source software may feel overwhelming at first (we've been there too!). But fear not, we're here to help you get started!
This section contains tips to help absolute beginners making their first contribution.
Workflow
We follow the usual GitHub workflow for contributions:
- Open an issue for the bug you're fixing or the feature you're developing, or, if the issue already exists, post a comment there
- Fork this repository
- Create a new branch in your forked repository
- Code code code! (And test test test!)
- When you're done, ensure that the test suite is running successfully
- Submit a pull request against the master branch of this repository
If you are new to this workflow, we suggest you to deepen your knowledge by reading more about it, for example this article.
Look for label "good first issue"
You'll find some issues labeled with "good first issue". These are issues that are pretty easy to solve, so we recommend tackling one of them if this is the first time you contribute. You can find "good first issues" by going to the issues panel and apply a filter, or by clicking here.
Any doubt?
If you still have any doubt, feel free to join our Discord and drop a message!
Community
Code of Conduct
The project and everyone involved in it is governed by our code of conduct. By participating, you are expected to uphold this code.
Language
The development language is English. This means that comments, variable/function/etc. names, issues, pull requests, documentation, etc., must be written in English.
We also encourage to write in simple English, by avoiding difficult and complex terms, since not everyone in the community is a native English speaker.
Want to chat?
If you want to reach out to ask something or just to have a chat, feel free to message us on our Discord channel. If you want to report a bug or propose a feature, please use GitHub issues instead.
Credits
This document has been inspired by the following contribution guidelines:
Commit message guidelines have been adapted from Robert Painsi Commit Message Guidelines.