DMX Development Guidelines (commits, repos, branches, releases, ...)
Indentation style
-
Use spaces, no TABs:
-
.java
: 4 spaces -
.js
,.json
,.html
,.css
: 2 spaces
-
-
No space at line end
-
Brace placement: K&R style, Java variant, that is opening brace in same line, e.g.:
private Topic checkCredentials(Credentials cred, AuthorizationMethod am) { if (am == null) { return dmx.getPrivilegedAccess().checkCredentials(cred); } else { return am.checkCredentials(cred); } }
Commit messages
- Every commit must be relatable to a ticket. Possibly create a ticket before commit.
- The ticket number is appended to the commit message in parenthesis, e.g.
My commit message (#91)
.
- The ticket number is appended to the commit message in parenthesis, e.g.
- A commit message must not be longer than
70
characters.
(Both GitHub and GitLab truncate messages that are longer, thus stripping the ticket reference. That must not happen.)
Repo names:
- A repo which contains only a DM4 line of development is named
dm4-
. - A repo which contains both a DM4 and a DM5 line of development is named
dmx-
. DM4 development takes place in branchdm4
. DM5 development takes place in branchmaster
. As soon as a DM4 plugin is adapted to DM5 the developer is supposed to rename the repo fromdm4-
todmx-
. - A repo which contains only a DM5 line of development is named
dmx-
. Development takes place in branchmaster
.
Branches
There are 2 kinds of branches
- long-term branches, e.g. "master", "dm4"
- short-term branches, that is bugfix branches or feature branches
Requirements for the master branch
- The master branch is always buildable and functional. A commit to the master branch must never break the build or any functionality that was working before.
- If a bugfix or a feature consists of more than 1 commit and these commits would temporarily break this rule a respective short-term branch must be created. Once the bugfix or feature is done the branch is merged into master. The short-term branch can be deleted then.
Mandatory steps for creating a release
- Update the version number. For Maven artifacts that is removing
-SNAPSHOT
from the version number (inpom.xml
). - Update the README, that is the build/installation/configuration/usage instructions.
- Update the CHANGELOG (resp. "Version History"). The CHANGELOG can be part of the README (my personal preference) or in a separate file. The CHANGELOG must list every release. Each CHANGELOG entry consists of:
- Release Number
- Release Date
- Short descriptions of new features/improvements/fixes
- Compatibility notes, e.g. required DM platform version, required versions of dependent plugins
- Do the release commit
- Tag the release commit with the version number, e.g.
1.3.2
.- Building a certain release is then as easy as checking out that tag and build.
- Switch the version number to the next
-SNAPSHOT
version number, e.g.1.3.3-SNAPSHOT
, and commit that change.- If at a later point it is decided there will be no
1.3.3
release but a direct jump to1.4
or2.0
the version number can be changed accordingly (inpom.xml
). 1.3.3 is just never released then. But it is mandatory to commit a-SNAPSHOT
version number immediately after the release commit. - For every release version number the entire repo must contain exactly one commit for that number (in
pom.xml
). Otherwise a build artifact would lie about its version number (the filename would say e.g.my-plugin-1.3.3.jar
suggesting it is a release when it is actually a SNAPSHOT), and the whole versioning/release effort becomes pointless.
- If at a later point it is decided there will be no
- Possibly publish the artifacts at Maven central
- Possibly close the milestone, and create a new one, so that issues can be assigned to them
- Possibly announce the release via website, mailing lists etc.
Managing multiple long-term branches
When dealing with multiple long-term branches, each one with independent releases, plus merges between them, things become more complex. E.g. the DeepaMehta 4 line of development takes place at long-term branch dm4
and is developed and released independently from DM5. Further long-term branches could be e.g. dm4-java10
, dm4-java11
.
DM4 Backend changes are still merged into DM5. There will be still DM4 releases, e.g. 4.9.1
, 4.9.2
, ... while DM5 is not yet released.
Merging a DM4 release into DM5 would create a merge conflict because (dozens of) diverging version numbers in all the POMs. The solution is to create a separate dead end branch for every DM4 release, e.g. 4.9.2-release
which only consists of the POM changes. That branch will never be merged. Thus the DM4 features/fixes are still merged to DM5, but the version numbers are not.
Black is the master branch, see https://github.com/jri/deepamehta/network
Tell me if you need help with long-term branches for your plugin project.
Note: this tickets does not contain an actual task. It is here for discussion. The final content will be moved to the Wiki then.