Skip to content
This repository has been archived by the owner on Apr 14, 2021. It is now read-only.

Latest commit

 

History

History
386 lines (268 loc) · 13.8 KB

CONTRIBUTING.md

File metadata and controls

386 lines (268 loc) · 13.8 KB

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

Naming

Whenever an acronym is included as part of a type name or method name, keep the first letter of the acronym uppercase and use lowercase for the rest of the acronym. Otherwise, it becomes impossible to perform camel-cased searches in IDEs, and it becomes potentially very difficult for mere humans to read or reason about the element without reading documentation (if documentation even exists).

Consider for example a use case needing to support an HTTP URL. Calling the method getHTTPURL() is absolutely horrible in terms of usability; whereas, getHttpUrl() is great in terms of usability. The same applies for types HTTPURLProvider vs HttpUrlProvider, etc.

Whenever an acronym is included as part of a field name or parameter name:

  • If the acronym comes at the start of the field or parameter name, use lowercase for the entire acronym

    • for example, String url;.

  • Otherwise, keep the first letter of the acronym uppercase and use lowercase for the rest of the acronym

    • for example, String defaultUrl;.

Formatting

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

Imports

It is forbidden to use wildcard imports (e.g., import static org.assertj.core.api.Assertions.*;) in Java code.

Ordering rules
  • import static all other imports
  • blank line
  • import all other imports
  • blank line

Javadoc

  • Javadoc comments should be wrapped after 80 characters whenever possible.
  • This first paragraph must be a single, concise sentence that ends with a period (".").
  • Place <p> on the same line as the first line in a new paragraph and precede <p> with a blank line.
  • Insert a blank line before at-clauses/tags.
  • Favor {@code foo} over <code>foo</code>.
  • Favor literals (e.g., {@literal @}) over HTML entities.
  • Use @since 5.0 instead of @since 5.0.0.

Test convention

Naming

  • All test classes must end with a Test suffix.
  • Example test classes that should not be picked up by the build must end with a TestCase suffix.

Assertions

  • Use org.assertj.core.api.Assertions wherever possible.
  • Use org.junit.Assert if sufficient.

Mocking

  • Use either Mockito or hand-written test doubles.
  • 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 travis to build and release Chutney JUnit. Build Status

Release Management

Update Changelog file

Do it first, because changelog updates should be part of the release being made

github_changelog_generator -u chutney-testing -p chutney-junit --token <YOUR_TOKEN> --since-tag <previous RELEASE_VERSION>
  • Copy-paste the generated content and use it to update CHANGELOG.md

Releasing

  mvn versions:set -DnewVersion=<RELEASE_VERSION> -DgenerateBackupPoms=false && mvn versions:set-scm-tag -DnewTag=<RELEASE_VERSION> -DgenerateBackupPoms=false
  git diff HEAD
  git add . && git commit -m "chore: Release <RELEASE_VERSION>"
  git push origin
  git tag <TAG_VERSION>
  git push origin <TAG_VERSION>

Prepare next development

  mvn versions:set -DnewVersion=<NEXT_DEV_VERSION> -DgenerateBackupPoms=false && mvn versions:set-scm-tag -DnewTag=HEAD -DgenerateBackupPoms=false
  git diff HEAD
  git add . && git commit -m "chore: Prepare next development <NEXT_DEV_VERSION>"
  git push origin

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

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.

Examples

Apache Lens:

Apereo:

Docassemble:

Tooling

nexB

nexB provides a set of tools to manage licenses and dependencies.

Licensed

Licensed helps to alert when a dependency license needs review

license-maven-plugin

This plugin helps to :

  • generate LICENCE file,
  • eventually generate NOTICE file (third-party-licenses).
  • bundle external licenses
  • generate license headers

maven-notice-plugin

This plugin helps to :

  • generate NOTICE file (third-party-licenses).

Maven-License-Verifier-Plugin

This plugin helps to :

  • fail build if licensing requirements are not met

Requirements are based on 4 license categories :

  • Forbidden
  • Valid
  • Missing
  • Unknown

Usage example

Valid and Forbidden licenses are defined in licenses.xml based on license name. Multiples names can be used to match a license.

Dependencies missing license are accepted by adding them in xml allowedMissingLicense.xml based on groupId and artifactId of the dependency.

Plugin goal can be used on the command line :

mvn se.ayoy.maven-plugins:ayoy-license-verifier-maven-plugin:verify

Or in a pom file : Parent pom

<plugin>
    <groupId>se.ayoy.maven-plugins</groupId>
    <artifactId>ayoy-license-verifier-maven-plugin</artifactId>
    <version>1.0.5</version>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>verify</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <licenseFile>${project.parent.basedir}/licenses.xml</licenseFile>
        <excludedMissingLicensesFile>${project.parent.basedir}/allowedMissingLicense.xml</excludedMissingLicensesFile>
        <failOnForbidden>false</failOnForbidden>
        <failOnMissing>false</failOnMissing>
        <failOnUnknown>false</failOnUnknown>
    </configuration>
</plugin>

Child pom

<plugin>
    <groupId>se.ayoy.maven-plugins</groupId>
    <artifactId>ayoy-license-verifier-maven-plugin</artifactId>
</plugin>

license-compatibility-checker

Helps to check dependencies licenses present in node_modules. It outputs compatibility level with the current project, based on a matrix.

tldrlegal

Helps to give an overview of dependencies licenses.

apache2-license-checker

Helps to give an overview of dependencies licenses and compatibility with ALv2.

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