Thanks a ton for considering contributing to an Amuzil project! We're always looking for new contributors, and we'd love to have you on board.
In this document, we'll go over the basics of contributing to an Amuzil project. We'll cover the following topics:
We expect all contributors to abide by our Code of Conduct.
There are many ways to contribute to an Amuzil project. Here are some of the most common ways:
IMPORTANT: if you want to report a security vulnerability that could potentially affect the security of our users, please contact us following the instructions in the Security Policy.
If you find a bug in an Amuzil project, please report it! We use GitHub Issues to track bugs. To report a bug, open a new issue in the project's repository. If you're not sure how to do that, check out this guide.
When you open a new issue, please follow the issue template.
If you have an idea for a new feature, please suggest it! We use GitHub Issues to track feature requests. To suggest a feature, open a new issue in the project's repository. If you're not sure how to do that, check out this guide.
When you open a new issue, please follow the issue template.
Are you unsure if your idea is a good fit for the project? Feel free to start a discussion, and we'll talk it over!
All documentation for our projects lives in the Amuzil Docs repository. We use GitHub Pull Requests to track documentation contributions. If you'd like to contribute to our documentation, please open a pull request there.
When you open a new pull request, please copy-paste the relevant pull request template. In addition to the template, please follow our conventions.
If you'd like to contribute code to an Amuzil project, please open a pull request! We use GitHub Pull Requests to track code contributions.
When you open a new pull request, please copy-paste the relevant pull request template. In addition to the template, please follow our conventions.
We have a few conventions that we follow when contributing to Amuzil projects. These conventions help us keep our projects consistent and easy to work with. We'll go over the conventions for each of the following topics:
We use Git through GitHub to track changes to our projects. We follow the GitHub Flow when contributing to our projects.
Commits must be atomic, and should be as small as possible. Commit messages should be clear and concise. You must follow the following format:
<gitmoji> <subject> [(#issue)]
<description>
Note in particular the spaces between the gitmoji, the subject and the issue, and the blank line between the subject and the description.
If possible, sign your commits.
We use Gitmoji to add meaningful emojis to our commit messages.
This helps us keep our commit messages consistent and easy to read.
You should use the unicode emoji rather than the text version of the gitmoji.
So, 📝, not :memo:.
To make things easier, there are tools that integrate Gitmoji into your IDE of choice.
For JetBrains IDEs, there is Gitmoji Plus: Commit Button, and for Visual Studio Code, there is Gitmoji. Both of these tools can be configured to use unicode emojis instead of text versions.
If your IDE of choice does not have a Gitmoji plugin, or you prefer to use a Git client, you can use the Gitmoji Cheat Sheet.
The subject of your commit message should be clear and concise. It should be around 50 characters, and must no longer than 72 characters. It must be written in the imperative mood, must start with a capital letter, and must not end with a period.
Good examples:
Add tomato sauce to pizza
Fix kitchen light
Bad examples:
Added tomato sauce to pizza
fix kitchen light
If your commit is related to a specific commit, you should reference it within parentheses.
For example, for a commit that adresses issue 42, (#123)
The description of your commit message can be as long as you need it to be. It is free form, and can be used to explain the changes you made in more detail. Be sure to use proper grammar and punctuation, and to keep your lines under 72 characters. Also, try to use a semi-professional tone.
Pull requests should be clear and concise. They should be as small as possible. Pull request titles should be clear and concise. They should start with a Gitmoji, then a space, then the title of the pull request. The title must be written in the imperative mood, start with a capital letter, must not end with a period, and must be no longer than 72 characters. Aim for around 50 characters.
In general, a pull request title should look quite similar to a commit message. However, it should summarise the changes made by all of the commits in the pull request.
Merge commits follow the same format, except for the fact that they reference the pull request, not the issue
🔀 <summary> <#pull-request>
<description>
The summary should be equal to the pull request title, except if there is a good reason it should not be.
A good examples:
🔀 Add form usage descriptions (#6)
Added VR & multikey usage descriptions for all forms,
as well as a small note to the Block description.
When contributing to an Amuzil project, you should create a new branch for your changes. You must follow the following format:
<type>/<name>
You should not use capital letters in your branch name.
Some good examples:
feature/tomato-sauce-on-pizza
bug/kitchen-light
Some bad examples:
JohnDoe/TomatoSauceOnPizza
michael/kitchen-light
tomato-sauce-on-pizza
What the type of your branch is depends on the project and the changes you're making. For example, some common types are:
feature, for new featuresbug, for bug fixesci, for changes to the CI/CD pipeline
Some projects may have more specific types, look for them in that project's readme.md.
The name of your branch should be clear and concise. It should be written in the imperative mood and kebab-case.
We use some quite opinionated code conventions. We'll go over them here. These conventions help us keep our projects consistent and easy to work with. Failure to follow these conventions may result in your pull request being rejected.
The best way to learn these conventions is to look at the code in the project you're contributing to. You'll learn them quick enough!
When naming general folders or files, unless if otherwise specified or impossible due to technical limitations, use kebab-case.
When naming packages/modules, code files, classes, functions, variables, etc., follow the conventions of the language you're using as recommended by the Naming Convention Project.
Additionally, follow the following conventions, taken from CodeAesthetics's "Naming Things in Code":
- Don't abbreviate names
- Wrong:
bpos,istack - Correct:
blockPosition,itemStack
- Wrong:
- Don't put types in variable names
- Wrong:
bIsValid,iCount - Correct:
isValid,count
- Wrong:
- Add units to variable names unless if the type tells you
- Wrong:
delay,length - Correct:
delayMilliseconds,lengthMeters
- Wrong:
- Don't put types in your types
- Wrong:
IDataTrait,IFlowControl - Correct:
DataTrait,FlowControl
- Wrong:
- Refactor if you find yourself naming code
Utils- Wrong:
InventoryUtils - Correct:
InventoryWatcher,InventoryToJSONConverter
- Wrong:
Additionally, watching Povilas Korop's "One Rule to Name Methods/Variables Clearly" is well worth your time. To summarise:
Bad:
public function report($from, $to, $type);Good:
public function getFinancialReportData(
string $fromDate,
string $toDate,
int $transactionType
): array;It should be clear what the function does, what the parameters are, and what it returns. Without having to read comments or the function's body.
A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail.
~ Uncle Bob Martin
We use automated code formatting tools such as Prettier to keep our code consistent and easy to read. You must use these tools when contributing to an Amuzil project.
By contributing to an Amuzil project, you agree that your contributions
will be licensed under its license, whatever it may be.
Look for a license.md at the root of the project's repository.