will/InfiniTime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add doc about branches, versioning and contributions

Browse Source
This commit is contained in:
JF002 2020-07-26 16:15:12 +02:00
parent 6222791aae
commit 8c77c8631d
4 changed files with 48 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -40,12 +40,17 @@ As of now, here is the list of achievements of this project:
## Documentation
### Build, flash and debug
- [Project branches](doc/branches.md)
- [Versioning](doc/versioning.md)
- [Build the project](doc/buildAndProgram.md)
- [Bootloader, OTA and DFU](./bootloader/README.md)
- [Stub using NRF52-DK](./doc/PinetimeStubWithNrf52DK.md)
- Logging with JLink RTT.
- Using files from the releases
## Contribute
- [How to contribute ?](doc/contribute.md)
### API
- [BLE implementation and API](./doc/ble.md)

12
doc/branches.md Normal file
View File

@ -0,0 +1,12 @@
# Branches
The branching model of this project is based on the workflow named [Git flow](https://nvie.com/posts/a-successful-git-branching-model/).
It is based on 2 main branches:
- **master** : this branch is always ready to be reployed. It means that at any time, we should be able to build the branch and release a new version of the application.
- **develop** : this branch contains the latest development that will be integrated in the next release once it's considered as stable.
New features should be implemented in **feature branches** created from **develop**. When the feature is ready, a pull-request is created and it'll be merge into **develop** when it is succesfully reviewed and accepted.
To release a new version of the application, when develop is considered stable, a **release** branch is created from **develop**. This can be considered as a *release candidate* branch. When everything is OK, this release branch is merged into **master** and the release is generated (a tag is applied to git, the release note is finalized, binaries are built,...) from **master**.
Git flow also supports the creation of **hotfix** branches when a bug is discovered in a released version. The **hotfix** branch is created from **master** and will be used only to implement a fix to this bug. Multiple hotfix branches can be created for the same release if more than one bugs are discovered.

24
doc/contribute.md Normal file
View File

@ -0,0 +1,24 @@
# How to contribute?
## Report bugs
You use your Pinetime and find a bug in the firmware? [Create an issue on Github](https://github.com/JF002/Pinetime/issues) explaining the bug, how to reproduce it, the version of the firmware you use...
## Write and improve documentation
Documentation might be incomplete, or not clear enough, and it is always possible to improve it with better wording, pictures, photo, video,...
As the documentation is part of the source code, you can submit your improvements to the documentation by submitting a pull request (see below).
## Fix bugs, add functionalities and improve the code
You want to fix a bug, add a cool new functionality or improve the code? See *How to submit a pull request below*.
## Spread the word
Pinetime is a cool open source project that deserves to be know. Talk about it around you, on social networks, on your blog,... and let people know that we are working on an open-source firmware for a smartwatch!
# How to submit a pull request ?
Your contribution is more than welcome!
If you want to fix a bug, add a functionality or improve the code, you'll first need to create a branch from the **develop** branch (see [this page about the branching model](./branches.md)). This branch is called a feature branch, and you should choose a name that explains what you are working on (ex: "add-doc-about-contributions"). In this branch, try to focus on only one topic, bug or feature. For example, if you created this branch to work on the UI of a specific application, do not commit modifications about the SPI driver. If you want to work on multiple topics, create one branch per topic.
When your feature branch is ready, make sure it actually works and do not forget to write documentation about it if necessary.
Then, you can submit a pull-request for review. Try to describe your pull request as much as possible: what did you do in this branch, how does it work, how is it designed, are there any limitations,... This will help the contributors to understand and review your code easily.
Other contributors can post comments about the pull request, maybe ask for more info or adjustements in the code.
Once the pull request is reviewed an accepted, it'll be merge in **develop** and will be released in the next release version of the firmware.

6
doc/versioning.md Normal file
View File

@ -0,0 +1,6 @@
# Versioning
The versioning of this project is based on [Semantic versionning](https://semver.org/) :
- The **patch** is incremented when we fix a bug on a **released** version (most of the time using a **hotfix** branch).
- The **minor** is incremented when we release a new version with new features. It corresponds to a merge of **develop** into **master**.
- The **major** should be incremented when a breaking change is made to the application. We still have to define what is a breaking change in the context of this project. For now, I suggest that it stays **0** until we have a fully functionning firmware suited for the final user.