🎉 First off, thanks for taking the time to contribute!
The following is a set of guidelines for contributing to Piral, which is hosted in the smapiot organization on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the email specified there.
Please find more information about how to set up your machine for developing Piral in the source documentation.
Before creating a bug report, please make sure that you first check the existing issues, as you might find that the issue is already reported. Fill out the required template, the information it asks for helps us resolve issues faster.
Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behavior 💻, and find related reports 🔎.
This section guides you through submitting an enhancement suggestion for Piral, including completely new features and minor improvements to existing functionality.
Before creating enhancement suggestions, please make sure that you first check the existing suggestions, as you might find that the enhancement has already been requested. Fill out the template, including the steps that you imagine you would take if the feature you're requesting existed.
Enhancements or general suggestions are tracked as GitHub issues. After you've determined that the enhancement is not already requested, go ahead and create an issue providing 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.
- Describe the current behavior and explain which behavior you expected to see instead and why.
- Include screenshots and animated GIFs which help you demonstrate the steps or point out the part of Piral to which the suggestion is related. Note: We usually live in code. Any code you can already show would be the best illustration.
The central repository holds four main branches with an infinite lifetime:
- main
- develop
- experimental
- documentation
We consider main
to be the main branch where the source code always reflects a production-ready state, and develop
to be the main branch where the source code always reflects a state with the latest delivered changes for the next release. When the source code in the develop
branch reaches a stable point and is ready to be released, all of the changes should be merged back into main. Therefore, each time when changes are merged back into main, this is a new production release.
The experimental branch is a special branch for an upcoming release that is unclear in scope and functionality. Releases from this branch should be considered unstable and might never reach production. No hotfixes or minor updates will be first-pushed to this branch. Instead, only (experimental) new features are (potentially exclusively) added to this branch.
The documentation branch is used for updates and fixes to the currently live (i.e., main
-build) documentation.
The following table gives an overview:
Branch Name | Builds Documentation | NPM Release/Tag | Version Suffix |
---|---|---|---|
main | yes (indirectly) | latest | (none) |
develop | no | next | beta |
experimental | no | canary | alpha |
documentation | yes | (none) | (none) |
If you don't know what to do - use develop
as a target for pull requests.
Next to the main branches main
and develop
, our development model uses a few supporting branches to aid parallel development between team members, ease tracking of features, and assist in quickly fixing live production problems. Unlike the main branches, these branches always have a limited lifetime, since they will be removed eventually.
The two main different types of branches we may use are:
- Feature branches, i.e.,
feature/*
- Hotfix branches, i.e.,
hotfix/*
Create a branch from develop
which must merge back into develop
.
Naming convention:
- anything except
main
,develop
,release/*
, orhotfix/*
- preferred
feature/{issue-id}-{issue-description}
, e.g.,feature/#123-add-foo
Create a branch from main
which must merge back into either main
and/or develop
. While a real hotfix will apply to both immediately, a simple fix will just be applied to develop
.
Naming convention:
hotfix/{new-patch-version}
, e.g.,hotfix/1.2.1
hotfix/{issue-id}-{issue-description}
, e.g.,hotfix/#123-fixed-foo-undefined
Hotfix branches are normally created from the main
branch (especially if they are applied to both main
and develop
, otherwise creating the branch from develop
may be okay as well). For example, say version 1.2 is the current production release running live and causing troubles due to a severe bug, while changes on develop are yet unstable.
Following is a short guide on how to make a valid Pull Request.
-
Firstly you need a local fork of the project, so go ahead and press the
fork
button in GitHub. This will create a copy of the repository in your own GitHub account and you'll see a note that it's been forked underneath the project name:Forked from smapiot/piral
. Clone the newly forked repository locally and set up a new remote that points to the original project so that you can grab any changes and bring them into your local copy.git remote add upstream git@github.com:smapiot/piral.git
You now have two remotes for this project on disk:
origin
which points to your GitHub fork of the project. You can read and write on this remote.upstream
which points to the main project's GitHub repository. You can only read from this remote.
-
Create the branch, following or Branching Model.
-
Do some work :) This is the fun part where you get to contribute to Piral 🚀.
-
Before pushing your code, there are a few more tasks that need to be performed:
-
Make sure that the test and build scripts run successfully
npm test lerna run build
-
Update the CHANGELOG.md following our convention
-
-
Commit and push the code to the origin.
git commit -m "Description of my awesome new feature" git push origin HEAD
-
After the code is successfully pushed to the origin repository, navigate to Piral repository and issue a new pull request.
You may merge the Pull Request once you have the sign-off of at least one other (core) developer, or if you do not have permission to do that, you may request the reviewer to merge it for you.