|
|
# Startin'blox contributions guidelines
|
|
|
|
|
|
## Commit messages
|
|
|
|
|
|
Start every commit message with a prefix indicating the level of modification. It can be either one of:
|
|
|
* **feature** for modification that add a significant new behavior to the software
|
|
|
* **update** for any modification of the behavior of the software that requires a specification update
|
|
|
* **bugfix** for any modification making the software comply with the specification
|
|
|
* **ui** for any modification of the software that affect its appearance but not its behavior
|
|
|
* **syntax** for any modification that do not affect the user, like a refactoring
|
|
|
|
|
|
example:
|
|
|
```
|
|
|
bugfix: set lookup field on @id
|
|
|
update: configurable fields (fix #6)
|
|
|
feature: representation of foreign keys as objects (fix #5)
|
|
|
feature: Federation model (fix #7)
|
|
|
```
|
|
|
|
|
|
## Release notes
|
|
|
|
|
|
when releasing a new version of the software, add a tag on the repository. Name it with the version number of the release and add a release note. The release notes should have 3 sections: **New features**, **Other changes** and **bug fixes**. You should check the list of all commit messages since last release to make those release notes.
|
|
|
|
|
|
## Experimental features
|
|
|
|
|
|
All new features should be marked in the release notes as *experimental*, and marked as such until their specification is validated.
|
|
|
|
|
|
An experimental feature is not guaranteed to work fully as expected, nor is it guaranteed to be maintained in future releases. Its specification can be changed at any moment in any commit.
|
|
|
|
|
|
## Specification change
|
|
|
|
|
|
Before making any change to a software that requires a specification updcate, please open an issue explaining why there is a need to do so. If possible, provide an example use case. If you think of a solution, you can provide it with a code example.
|
|
|
|
|
|
This issue *should* be shared with all the other contributors so that every one can discuss it, until a decision is made. Then new issues should be created to describe the technical details of implementation.
|
|
|
|
|
|
## Documentation
|
|
|
|
|
|
Every non experimental features *should* be documented in the repository README.md.
|
|
|
|
|
|
Experimental features *can* be documented, but their documentation should mention clearly that the feature is experimental and is not guaranteed to continue to work in the future. |
|
|
\ No newline at end of file |