Skip to content
This repository has been archived by the owner on Feb 23, 2024. It is now read-only.

Latest commit

 

History

History
178 lines (117 loc) · 7.58 KB

CONTRIBUTING.md

File metadata and controls

178 lines (117 loc) · 7.58 KB
Raw

Contributing

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 as you like
    • WARNING - Do not modify the master 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 master or any other of ours
    • ex. on your branch, do :
      • git fetch --all --prune
      • git rebase --no-ff origin/master
  4. Test your changes and make sure everything is working
  5. Submit your Pull Request
    • 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 :

Code convention

Try to follow Kotlin coding conventions.

We use an .editorconfig file, please use a tool accepting it and do not override rules.

Concerning tests mocking :

  • Use either Mockito or hand-written test doubles.
  • Use org.springframework.test.web.servlet.MockMvc to mock REST HTTP endpoints
  • Do not use PowerMock
    • We consider it to be sign of a code-smell

Branch convention

  • wip/ unstable code, to share between developers working on the same task
  • feat/ stable code of new feature, to be merged if validated
  • bugfix/ stable code of correction (PROD / VALID)
  • tech/ stable code, purely technical modification like refactoring, log level change or documentation

Commit message

As a general rule, the style and formatting of commit messages should follow the guidelines in How to Write a Git Commit Message.

  • Separate subject from body with a blank line
  • Limit the subject line to 50 characters
  • Capitalize the subject line
  • Do not end the subject line with a period
  • Use the imperative mode in the subject line
  • Wrap the body at 72 characters
  • Use the body to explain what and why vs. how

Alternative:

Build Process

We use github actions to build and releas this library. CI

Release Management

Update Changelog file

Do it first, because changelog updates should be part of the release being made.
Check page: 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

We use Reckon gradle plugin.

Release is just pushing a tag with version information :

  ./gradlew reckonTagCreate -Preckon.stage=<final|snapshot> -Preckon.scope=<major|minor|patch>
  git push origin <TAG_VERSION>

Update Github release

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 Chutney 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 Chutney, as a plugin.

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

Any distribution of Chutney 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 details, see deps/superwidget/
  • do not list dependencies under the ALv2