Skip to content

Latest commit

 

History

History
224 lines (140 loc) · 9.54 KB

CONTRIBUTING.md

File metadata and controls

224 lines (140 loc) · 9.54 KB
Raw

How to contribute

We would love you to contribute to this project. You can do so in various ways.

Contribute your knowledge

Help others by participating in our forum.

Before you ask a question, search the forum. The answer may have already been provided.

File bugs or feature requests

File bugs you found in the code or features you would like to see in the future in our issue tracker.

  • Register yourself on our issue tracker
  • Search the list of open issues first, your bug or feature may have already been reported
  • When filing a bug
    • Be concise
    • Qualify steps to reproduce a problem
    • Specify environment you found the bug in (library version etc.)
    • If possible, attach a test case that reproduces the problem

Contribute code

You can contribute code that fixes bugs and/or implements features.

Write Tests

Best practices for writing test cases:

  • write JUnit4-style tests, not JUnit3
  • Project camunda-engine: If you need a process engine object, use the JUnit rule org.camunda.bpm.engine.test.util.ProvidedProcessEngineRule. It ensures that the process engine object is reused across test cases and that certain integrity checks are performed after every test. For example: 
    public ProcessEngineRule engineRule = new ProvidedProcessEngineRule();

@Test
public void testThings() {
  ProcessEngine engine = engineRule.getProcessEngine();

  ...
}
  • Project camunda-engine: As an alternative to the above, you can extend extend the org.camunda.bpm.engine.test.util.PluggableProcessEngineTest class. The class already provides an instance of the ProvidedProcessEngineRule, as well as the ProcessEngineTestRule that provides some additional custom assertions and helper methods.
    • However, if you need to make modifications to the ProcessEngineConfiguration, then please use the ProcessEngineBootstrapRule as described below.
  • Project camunda-engine: If you need a process engine with custom configuration, use the JUnit rule org.camunda.bpm.engine.test.util.ProcessEngineBootstrapRule and chain it with org.camunda.bpm.engine.test.util.ProvidedProcessEngineRule like so: 
    protected ProcessEngineBootstrapRule bootstrapRule = new ProcessEngineBootstrapRule(configuration -> {
    // apply configuration options here
});
protected ProvidedProcessEngineRule engineRule = new ProvidedProcessEngineRule(bootstrapRule);

@Rule
public RuleChain ruleChain = RuleChain.outerRule(bootstrapRule).around(engineRule);

Coding styles

  • tabs as spaces / tab size 2 (all files)
  • If you created a number of commits, squash your work into a few commits only.
  • Create commit messages that adhere to our commit message style(see below).

License headers

Every source file needs to contain the following license header at the top:

Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH
under one or more contributor license agreements. See the NOTICE file
distributed with this work for additional information regarding copyright
ownership. Camunda licenses this file to you under the Apache License,
Version 2.0; you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

The header can be added manually, it can be set through your IDE's settings so that it is added to new source files automatically, or by running mvn clean install -Plicense-header-check. The last option will run a License Header plugin that will go through all the source files and add a license header to the ones that don't have one. It will also re-format an incorrectly formatted license header.

It should be noted that Java source files from a contribution, that do not contain a valid license header, will not be merged with the codebase.

Contributor License Agreement

In order to merge your contribution you have to sign our Contributor License Agreement (CLA) (which needs to be done only once). The CLA contains the terms and conditions under which the contribution has been submitted. Keep in mind without signed CLA the contribution will not be merged.

Commit Message Conventions

This page defines a convention for commit messages for camundaBPM related projects.

All commits pushed to the camunda BPM repositories must conform to that convention.

The contents of this page are partly based on the angular commit messages document.

Purpose

The commit message is what is what describes your contribution. Its purpose must therefore be to document what a commit contributes to a project.

Its head line should be as meaningful as possible because it is always seen along with other commit messages.

Its body should provide information to comprehend the commit for people who care.

Its footer may contain references to external artifacts (issues it solves, related commits) as well as breaking change notes.

This applies to all kind of projects.

Format

Short form (only subject line)

<type>(<scope>): <subject>

Long form (with body)

<type>(<scope>): <subject>

<BLANK LINE>

<body>

<BLANK LINE>

<footer>

First line cannot be longer than 70 characters, second line is always blank and other lines should be wrapped at 80 characters! This makes the message easier to read on github as well as in various git tools.

Subject Line

The subject line contains succinct description of the change.

Allowed

  • feat (feature)
  • fix (bug fix)
  • docs (documentation)
  • style (formatting, missing semi colons, …)
  • refactor
  • test (when adding missing tests)
  • chore (maintain)
  • improve (improvement, e.g. enhanced feature)

Allowed

Scope could be anything specifying place of the commit change. For example in the camunda-modeler project this could be import, export, property panel, label, id, ...

text

  • use imperative, present tense: change not changed nor changes or changing
  • do not capitalize first letter
  • do not append dot (.) at the end

Message Body

  • just as in use imperative, present tense: change not changed nor changes or changing
  • include motivation for the change and contrast it with previous behavior

Message Footer

Breaking changes

All breaking changes have to be mentioned in footer with the description of the change, justification and migration notes

BREAKING CHANGE: Id editing feature temporarily removed

    As a work around, change the id in XML using replace all or friends

Referencing issues

Closed bugs / feature requests / issues should be listed on a separate line in the footer prefixed with "Closes" keyword like this:

Closes #234

or in case of multiple issues:

Closes #123, #245, #992

More on good commit Messages

FAQ for Geeks

Why to use imperative form in commit messages?

I.e. why to use add test for #foo versus added test for #foo or adding test for foo?

Makes commit logs way more readable. See the work you did during a commit as a work on an issue and the commit as solving that issue. Now write about for what issue the commit is a result rather than what you did or are currently doing.

Example: You write a test for the function #foo. You commit the test. You use the commit message add test for #foo. Why? Because that is what the commit solves.

How to categorize commits which are direct follow ups to merges?

Use chore(merge): <what>.

I want to commit a micro change. What should I do?

Ask yourself, why it is only a micro change. Use feat = docs, style or chore depending on the change of your merge. Please see next question if you consider commiting work in progress.

I want to commit work in progress. What should I do?

Do not do it or do it (except for locally) or do it on a non public branch (ie. non master / develop ...) if you need to share the stuff you do.

When you finished your work, squash the changes to commits with reasonable commit messages and push them on a public branch.