The contribution structure for this repository is based on the Git Etiquette. Feel free to read that for more info Also, please note that by contributing to this project, you are agreeing to the terms and conditions outlined in the Developer Certificate of Origin.
(back to top) (back to section)
(back to top) (back to section)
(back to top) (back to section)
(back to top) (back to section)
(back to top) (back to section)
Labels can either be assigned automatically by the automation or manually by the user. It is best to let the automation handle the assignment of labels marked as "automatically" and not add them manually to an issue or pull request.
Issues and Pull Requests should always have exactly one Categorical label, Status label, and Descriptive label.
These are labels that describe the nature of the proposed changes, and how they affect the project. These labels should be added manually.
These are labels that describe the nature of the issue itself. These are typically added automatically.
These are labels that discribe certain attributes of issues and PRs, to make it easy for contributors to find and address them quickly. Some are automatic, and some are manual.
These are labels that describe the development status of the changes. These can be added manually, but are typically updated automatically by Actions when development of the features follows the usual flow.
(back to top) (back to section)
| Label Name | Label Type | Description | Manually or Automatically | Label / Status Field |
|---|---|---|---|---|
| Docs 📝 | Descriptive | Changes to documentation only | Manually | Label |
| Feat 🆕 | Descriptive | A new feature | Manually | Label |
| Style 🖌️ | Descriptive | Changes to formatting. (e.g. spreading lines, tabbing, keyword casing...) | Manually | Label |
| Test ☑️ | Descriptive | Adding/correcting existing tests | Manually | Label |
| Refactor 🧮 | Descriptive | Restructuring of the code without changing functionality | Manually | Label |
| Bugfix 🩹 | Descriptive | A bug fix | Manually | Label |
| Chore 🧹 | Descriptive | Routine maintenance (e.g. bump version, update changelog or deps) | Manually | Label |
| Meta 👨💻 | Descriptive | Changes development files, but not product code (e.g. changes to .gitignore, workflows, readme...) | Manually | Label |
| Backend ⚙️ | Categorical | Functional/mechanical changes, development changes | Automatically | Label |
| Frontend 🖥️ | Categorical | Visual/graphical changes | Automatically | Label |
| Design 🎨 | Categorical | Artistic/stylistic changes | Automatically | Label |
| Unassigned ❕ | Flag | Currently nobody has been assigned to it | Automatically | Label |
| Unlabeled ❗ | Flag | No labels have been added | Automatically | Label |
| Backlog 📜 | Status | Tasks that have not yet been started or left unfinished | Both | Both |
| In Progress 🛠 | Status | Currently in the process of being worked on | Both | Both |
| Ready for Review 🔍 | Status | Changes are complete and ready for review (PR only) | Both | Both |
| Done ✔️ | Status | Task has been completed or closed | Both | Both |
(back to top) (back to section)
- Open a new issue inside the repository.
- Choose one of the cards or templates (Backend, Frontend, or Design). This determines the Categorical label.
- Follow thew instructions to fill out the template.
- Pick one (and only one) Descriptive label from the label list.
- Submit your issue. The Backlog 📜 label will be automatically added to fill the Status label.
- Once a contributor makes a pull request to address the issue, the Status label will be automatically updated to In Progress 🛠. See Creating a Pull Request.
- A team member will close the issue once the linked pull request is merged. The Status label will be automatically updated to Done ✔️.
(back to top) (back to section)
- Choose an issue to address.
- Fork the repository, if needed.
- Create a new branch. The branch name should be formated as
<desc>/<num>/<title>. (e.g.feat/#7/add-roadmap)<desc>is the Descriptive label from the issue. (e.g.featfor a Feat 🆕 issue)<num>is the issue number. (e.g.#7)<title>is the title of the branch. This should be one to three words, separated by dashes, that describe the changes. (e.g.add-roadmap)
- Commit your initial changes. This can be done on the website or cloned to your local machine and pushed to the branch.
- Open a Draft PR and link the addressed issue as soon as possible. This will allow the automation to start tracking your progress, and prevent others from duplicating your work.
- NOTE: you should always open pull requests to the
devbranch, never themainbranch. Themainbranch is reserved for stable releases, and should only be updated by merging thedevbranch. All pull requests tomainwill be rejected.
- NOTE: you should always open pull requests to the
- When you are ready, submit your PR for review. A team member will be assigned to review your changes and guide you through the merging process.
- If the reviewer requests changes, make the requested changes and commit them to the branch. Once you have addressed all the requested changes, you may request another review.
- Once the reviewer approves your changes, the reviewer will merge your changes into the
devbranch, and the Status label will be automatically updated to Done ✔️. The reviewer will then close the issue.
Congradulations! You have successfully made your first contribution to this repository! Your contributions will forever be remembered in the commit history of this repository, and you will be listed as a contributor in the project's credits.
(back to top) (back to section)
This repository's workflow strategy is based on the Git Flow strategy, where every update or addition is made in temporary branches called feature branches. Every new branch created addresses an open issue, whether it be a feature request or a bug report.
The main branch is the production branch, which is the version that is released and is always the most stable one. No pull requests are made to the main branch, and the main branch only changes when a new release or beta is pushed from the dev branch.
The dev branch is where all pull requests are made. It is the base of all feature branches, and is the home of active development and experimental features. New features are constantly pulled to the dev branch from feature branches. However, even though the dev branch is less stable than main, it should never be broken, and should always be usable for those who want to test the latest features. Nightly builds are made from the dev branch on a regular basis.
The actual Git Flow strategy also includes release and hotfix branches, which are not included in this repo's workflow structure. All releases should be managed using the Git tagging system, and hotfixes should be made in feature branches.
| Name | Description |
|---|---|
| main | A production branch |
| dev | A development branch |
| feature branches | Each issue is one feature branch |
(back to top) (back to section)
- The merge order is from feature branch to development branch, and then from development branch to main branch. This order ensures that changes are tested in the development branch before they are merged in to the main branch.
- Simply said: the merge order is: feature > dev > main.
- Forward merges follow the order above, and are always done via pull requests. and should always be merged using a Merge Commit. This ensures features and changes are easy to keep track of.
- Backward merges are done in reverse, and are typically used to update feature branches with changes from the development branch. These merges should always be done using a Rebase Merge if possible. This ensures that the feature branch is up to date with the development branch, while preventing innecessary git spaghetti. Where a rebase merge fails, a Merge Commit is acceptable.
- Always open pull request from feature branch to
devbranch (never tomain!). - Each issue has one and only one associated feature branch.
- Never merge changes directly to
devormain! If something should be changed, open an issue to let everyone know. Then you can make a pull request if you want to address it yourself. This ensures that changes are peer reviewed and any potential problems can be identified before the changes are applied to the branch. Even if there are problems accepted via a pull request, merging makes it easy to revert changes if needed.