Skip to content

Latest commit

 

History

History
314 lines (234 loc) · 12.4 KB

CONTRIBUTING.md

File metadata and controls

314 lines (234 loc) · 12.4 KB
Raw

Contributing to Coaty JS Framework

Contributions to the Coaty JavaScript framework are welcome and appreciated. If you wish to contribute please follow the guidelines described in this document.

Table of Contents

Workflow

Contributions should be incorporated into the repository using pull requests on a separate branch. We use the GitHub Pull Request Workflow. The mentioned link is the recommended documentation to read and understand this workflow.

Our Git development workflow includes the following steps:

  • Each repository has a master and a develop branch.
  • Mainline of development is always on the develop branch.
  • The master branch only contains releases that could be deployed to production. Do not develop on this.
  • For a new feature or a patch, you can create a separate local branch branched from develop. These branches should be named "feat-<name-of-feature>" or "fix-<name-of-issue>". If the feature/patch is small you can also do it on the local develop branch directly.
  • During development, commits should not be pushed to the remote as they should not be made public at that time. Also, it is easier to make changes to the local commit history (e.g. amend commit, rewrite history) if the branch is kept local only.
  • When a feature is completed the commits should be merged back (preferably via fast-forward) into the local develop branch.
  • Then, on the local develop branch the feature is released according to the CONTRIBUTING guidelines of the project (including versioning, tagging, creating changelog and documentation, etc.).
  • Finally, the local develop branch is pushed and merged into the master branch (via fast-forward).
  • Local and remote master and develop branches should now be even.
  • The local feature/patch branch can be deleted.

Automatic versioning and changelog management

We are using the Conventional Commits Style for our commit messages:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Conventional Commits Style helps structuring Git commit messages in a way that allows automatic generation of changelogs. These conventions form the basis for automatic version bumping and CHANGELOG management when cutting a new release.

For details, see the section Release Coaty framework below.

License and Copyright Notice

Coaty JS source code is licensed under the MIT License. Attach a license and copyright notice to the top of each created source files as follows:

/*! Copyright (c) <year> <contributor>. Licensed under the MIT License. */

<year> specifies the year of first publication and must not be changed when you modify the contents of the file later on. Do not add additional copyright notices or dates when the work is revised at a future time.

Contributions without this header on each new source file won't be accepted.

The meaning of source file covers all files, which allow adding a comment easily (e.g. .js, .ts, .css) and contribute to the core value of the project by adding originality (e.g. no .editorconfig, etc.).

Documentation and media work (such as icons) should be licensed under a Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).

Coding Style

Please ensure that all your contributions are aligned to our obligatory Coding Style Guide.

The framework includes a custom linter configuration that conforms to our style guide and should also be used in Coaty application projects.

Developer Notes

Please take a look at the DEVNOTES.md file in the project root folder. It contains important notes for framework developers, regarding specific issues and points to take care of.

Build Coaty framework

Install the project's dependendies on the root folder:

npm install

Note: Peer dependencies will be installed automatically because they have also been defined as devDependencies (for executing the framework's tests).

The following npm scripts are used to control the build process:

# Build distribution package and lint the source code
npm run build

# Build distribution package but do not lint the source code
npm run build:nolint

# Lint TypeScript source files
npm run lint

The build command generates an ECMAScript ES5 distribution package under dist by running the TypeScript compiler on the TypeScript source files under /ts.

Builds include inline source maps in the generated JS files and have comments included. When bundling the framework into an application project, source maps and comments can be removed by applying appropriate tools.

Generate Coaty framework documentation

First, ensure that the framework has been build as explained in the previous section. Then, generate HTML documentation from the TypeScript source code and the included JavaDoc comments:

npm run doc

The generated documentation is written to the docs/api/ folder and accessible by index.html.

Test Coaty framework

The framework test suite contains unit, component and E2E integration tests:

# Run the test suite with default MQTT binding
npm run test

# Run the test suite with verbose output with default MQTT binding
npm run test:debug

# Run the test suite with a given binding, e.g. wamp
npm run test <binding-name>

# Run the test suite with verbose output with a given binding, e.g. wamp
npm run test:debug <binding-name>

Before running the test suites, build the framework. Test output is written to the console. Additionally, a JUnit XML output file is written to be used when running in a CI environment such as Jenkins. By default, the JUnit XML file is written to the test/reports folder.

For CI environments you can adjust the test configurations by modifying the npm config settings provided in the framework's package.json. The default values provided here can be overwritten by npm config set <key> <value>.

test_config          Jasmine config options
test_broker_config   the Coaty broker config (for MQTT binding only)
test_reports_dir     where JUnit XML output is written

To support debugging of communication-related tests use the test:debug target. It provides detailed logging on the messaging transport layer.

You can specify the name of a specific communication binding to run all tests with, e.g. "mqtt" or "wamp". If not specified, the MQTT binding is used. If specified, the corresponding binding package @coaty/binding.<binding-name> must be installed as a devDependency. Note that broker-based bindings require additional communication infrastructure that must be installed separately.

For the MQTT binding, the test suite uses the Coaty MQTT broker that is preinstalled as a local npm dev dependency. Broker options are configured in ./test/support/mqtt.broker.config.json. To avoid collisions with other brokers running on the local machine, the test broker listens to MQTT port 1898 and http/ws port 1998 (typically brokers use 1883/9883 by default). Note that the broker is only running while the test suite is executed.

For the WAMP binding, the test suite uses the Crossbar.io WAMP router which must be installed separately. The installed router is started automatically before running the tests, using the router configuration in ./test/support/wamp.router.config.json. After finishing the test, the router is stopped automatically.

Release Coaty framework

The release process separates local steps that only affect the local git repo from remote steps that affect the repository and the npm registry:

  1. npm run cut-release - prepare a new release, including automatic versioning, conventional changelog and tagging.
  2. npm run push-release - push the prepared release to the remote git repo
  3. npm run publish-release - publish the package on npm registry.

Prepare a release

To prepare a new release locally on the current branch, run the cut-version npm run script. It

  1. computes a new package version and bumps it,
  2. builds the distribution packages and generates HTML documentation,
  3. updates the CHANGELOG with release information from the conventional commits,
  4. commits all pending changes,
  5. creates an annotated git tag with the new release version.
npm run cut-release (recommended | first | major | minor | patch | <semantic version>) ["<release note>"]

# examples
npm run cut-release patch
npm run cut-release recommended "This is a release note."
npm run cut-release 2.0.0-beta.3 "This is another release note."

If supplied with recommended, a recommended version bump is computed based on conventional commits. An error is reported, if the recommended version cannot be computed because there are no commits for this release at all.

If supplied with first, the package version is bumped to the current version specified in package.json.

If supplied with major, minor, or patch, the package version is incremented to the next major, minor, or patch version, respectively.

If supplied with a valid semantic version (e.g. 1.2.3 or 1.2.3-beta.5) this version is bumped. You can also use this option to create a prerelease.

In any of the above cases except first, an error is reported if the new version to be bumped is equal to the current package version.

Note: the auto-generated release information in the CHANGELOG only includes feat, fix, and perf conventional commits. Non-conventional commits are not included. Other conventional commit types such as docs, chore, style, refactor are not included. However, if there is any BREAKING CHANGE, this commit will always appear in the changelog.

Note: if you want to edit the auto-generated CHANGELOG afterwards, you should amend this change to the last commit (git commit --amend). Ensure that the tag set with the last commit is re-added by calling git tag -a -f -m "chore(release): v<new-version>" v<new-version> where <new-version> is substituted by the new package version number.

If supplied with an optional release note, the given text is prepended to the release information generated by conventional commits. The text should consist of whole sentences.

Push a release

After executing the cut-release npm run script, the new release commits and the release tag on the current branch are ready to be pushed to the remote git repo server.

npm run push-release

Afterwards, depending on your GIT workflow, you can merge your remote branch into master.

Note that the push-release script may error because the git private key authentication has not been set up properly. In this case, you can perform this step manually using your preferred GIT client. Do NOT forget to push the release tag, too. You can push both the release commits and the annotated tag by executing git push --follow-tags.

Publish a release

To publish the framework distribution package to an npm registry, you can use the following script:

npm run publish-release [npm-tag]

If supplied with npm-tag, the published package is registered with the given tag, such that npm install <package>@<npm-tag> will install this version. If not supplied with npm-tag, the latest tag is registered. In this case, npm install installs the version tagged with latest.

Note that authentication is required for publishing, so you need to set up an appropriate account at the npm registry server first. Then, create an npm authentication token (on npm website or by invoking npm adduser) and paste the created authentication information into your ~/.npmrc.

Copyright (c) 2018 Siemens AG. This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.