Skip to content

Latest commit

 

History

History
129 lines (85 loc) · 5.5 KB

CONTRIBUTING.md

File metadata and controls

129 lines (85 loc) · 5.5 KB
Raw

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.

Please note we have a code of conduct, please follow it in all your interactions with the project.

Issues and feature requests

You've found a bug in the source code, a mistake in the documentation or maybe you'd like a new feature? You can help us by submitting an issue to our GitHub Repository. Before you create an issue, make sure you search the archive, maybe your question was already answered.

Even better: You could submit a pull request with a fix / new feature!

Pull request process

  1. Search our repository for open or closed pull requests that relate to your submission. You don't want to duplicate effort.

  2. You may merge the pull request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.

(Code) Quality checks

Every merge-request triggers a build process which runs various checks to help maintain a quality standard. All JSON, Markdown, PHP, and Yaml files are expected to adhere to these quality standards.

These tools fall into two categories: PHP and non-PHP.

PHP

The PHP specific tools used by this build are:

The automated checks with these tools are run via GitHub Actions.

As most of these tools are included as Composer require-dev packages, they can be run locally with PHP.

For the Parallel Lint check, the composer lint script has been added for convenience.

The Security Checker package is not included in the Composer configuration. An executable can be downloaded suitable for your operating system from their releases page.

Alternatively, these tools can be run using docker run, through the Docker images provided by Pipeline-Component.

Non-PHP

The non-PHP specific tools used by this build are:

  • jsonlint to verify that all JSON files use a consistent code style.
  • remark-lint to verify that all markdown files use a consistent code style.
  • yamllint to verify that all Yaml files use a consistent code style.

These tools are also run as GitHub actions. All the checks can be run locally using act. Alternatively they can be run using docker run, as all checks use Docker images provided by Pipeline-Component.

Finally, they could be run locally using NodeJS, Ruby, PHP, or whatever the tool is written in. For details please consult the relevant tool's documentation.

Release process

To make it possible to automatically generate a changelog, all tickets/issues must have a milestone and at least one label.

A changelog can be generated using the github-changelog-generator.(1)

Our release versions follow Semantic Versioning.

New releases (and any related tags) are always created from the master branch.

To create a new release:

  1. Make sure all closed tickets and MRs have a label.

  2. Make sure all closed tickets and MRs are added to the milestone that is to be released.

  3. Move any open tickets to the next milestone (create a new one if needed).

  4. Generate a changelog by running github_changelog_generator in the project root:(2)

    github_changelog_generator --future-release "${sVersion}" --header --output --unreleased-only 2>/dev/null

    Where sVersion contains the new version to release.

  5. Use GitHub "Draft a new release" functionality to draft a new release (this also creates a tag).

  6. Close the milestone for the version that was just released.

Footnotes

  1. All settings needed for the changelog-generator are set in .github_changelog_generator file.

  2. A convenience script is present at bin/generate-changelog.sh that will install the changelog-generator, if it is not present, and run the appropriate github_changelog_generator command. The script requires BASH to run. It should be run from the project root, similar to github_changelog_generator.