Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
246 lines (161 loc) · 9.24 KB

CONTRIBUTING.md

File metadata and controls

246 lines (161 loc) · 9.24 KB
Raw

Contributing

🇫🇷 Français | 🇺🇸 English

Summary

How to contribute to the documentation

To contribute to this documentation (README, CONTRIBUTING, etc.), we conforms to the CommonMark Spec

How to make a Pull Request

  1. Fork the repository and keep active sync on our repo
  2. Create your working branches conforming to conventional branch.
    • WARNING - Do not modify the main branch nor any of our branches since it will break the automatic sync
  3. When you are done, fetch all and rebase your branch onto our main or any other of ours
    • ex. on your branch, do :
      • git fetch --all --prune
      • git rebase --no-ff origin/main
  4. Test your changes and make sure everything is working
  5. Submit your Pull Request to the dev branch (main branch is only allowed for project owners)
    • Do not forget to add reviewers! Check out the last authors of the code you modified and add them.
    • In case of doubts, here are active contributors :
      • Jehan BOUSCH

Code convention

Best Practices

As a general rule you have to follow the Google Java Style Guide.

Formatting

All Java source files must conform to the Formatting section of Style Guide

Javadoc

All Java source files must use the Javadoc section of Style Guide.

Test convention

To run all the tests of the project use the following command :

mvn test

Naming

  • Tests are located in src/test
  • When you write a test file name should end with Test.java.
  • All test functions must start with a test_ prefix.

Test framework

  • Use org.junit as test framework.

Mocking

  • Mock interfaces should have the same name as the original ending with Mock

Example: TICCoreStream --> TICCoreStreamMock

Branch convention

We conform to conventional branch.

Commit changes

We conform to conventional commit.

Dependency management

Project dependencies are listed in the pom.xml file.

To see modules really "used" by the application use the following command :

mvn dependency:list

For more detailed documentation please refer to Apache Maven Dependency Plugin.

Build Process

To build the application TIC2WebSocket in the project directory use the following command :

mvn clean package

Release Management

Release management is exclusively done on GitHub

Releasing

TIC2WebSocket releases are available only on GitHub.

Update Changelog file

Always update the changelog before creating a release. This ensures the changes are documented for the release being created. Refer to this page for guidance on automatically generated release notes: Automatically generated release notes

Do not hesitate to update the release note generated especially the titles of pull request :) Use it to update CHANGELOG.md

Releasing version only on GitHub

General information

  • Releases to GitHub only update the last digit of the version (e.g., 2.7.1.1 or 2.9.4.2).
  • The subsequent snapshot version remains unchanged.
  • The CHANGELOG.md file is committed to the tag.
  • Pull requests are not required for releases to GitHub.

Step by step

git switch -c release/<RELEASE_VERSION>
git add CHANGELOG.md (see Update Changelog file section)
git add .
git diff --staged
git commit -m "chore: Release <RELEASE_VERSION>"
  • Then tag and push.
git tag <TAG_VERSION>
git push origin <TAG_VERSION>
  • Update the release note on github

Licensing

We choose to apply the Apache License 2.0 (ALv2) : http://www.apache.org/licenses/LICENSE-2.0

As for any project, license compatibility issues may arise and should be taken care of.

Concrete instructions and tooling to keep TIC2WebSocket ALv2 compliant and limit licensing issues are to be found below.

However, we acknowledge topic's complexity, mistakes might be done and we might not get it 100% right.

Still, we strive to be compliant and be fair, meaning, we do our best in good faith.

As such, we welcome any advice and change request.

To any contributor, we strongly recommend further reading and personal research :

How to manage license compatibility

When adding a new dependency, one should check its license and all its transitive dependencies licenses.

ALv2 license compatibility as defined by the ASF can be found here : http://apache.org/legal/resolved.html

3 categories are defined :

  • Category A : Contains all compatibles licenses.
  • Category B : Contains compatibles licenses under certain conditions.
  • Category X : Contains all incompatibles licenses which must be avoid at all cost.

As far as we understand :

If, by any mean, your contribution should rely on a Category X dependency, then you must provide a way to modularize it and make it's use optional to TIC2WebSocket, as a plugin.

You may distribute your plugin under the terms of the Category X license.

Any distribution of TIC2WebSocket bundled with your plugin will probably be done under the terms of the Category X license.

But "you can provide the user with instructions on how to obtain and install the non-included" plugin.

References :

How to comply with Redistribution and Attribution clauses

Lots of licenses place conditions on redistribution and attribution, including ALv2.

References :

LICENSE file

In Source distribution

This file contains :

  • the complete ALv2 license.
  • list dependencies and points to their respective license file
    • Example : This product bundles SuperWidget 1.2.3, which is available under a "3-clause BSD" license. For deails, see deps/superwidget/
  • do not list dependencies under the ALv2

NOTICE file

In source distribution

The NOTICE file is not for conveying information to downstream consumers -- it is a way to compel downstream consumers to relay certain required notices.

Unresolved questions - HELP WANTED -

  • Should test dependencies be taken into account for source distribution ?
    • It appears to be YES
  • Should build time dependencies be taken into account ?
    • It appears to be NO but might depend on the actual stuff done by this dependency