This document describes the contribution process and requirements of the FINOS Fluxnova project.

Please also see our Governance guidelines, and FINOS Code of Conduct & Collaborative Principles.

• Ways to contribute
• Browse our issues
• Build from source
• Create a pull request
• Contribution checklist
• Contributor License Agreement (CLA)
• Commit message conventions
• License headers
• Review process

We’re excited you’re here and want to contribute to Fluxnova! This guide outlines how you can contribute effectively and collaboratively.

Help others by participating in our forum. Please read the Forum FAQ before you start. **Forum FAQ - Needs To Be Reviewed **

Help others by participating in discussions on GitHub or by joining our mailing list fluxnova@lists.finos.org (email help@finos.org to add you to the list).

Found a bug in the code or have a feature that you would like to see in the future? Search our open issues if we have it on the radar already or create a new issue otherwise.

Try to apply our best practices for creating issues:

• Only Raise an issue if your request requires a code change in Fluxnova Platform 1.0.0

• If you have an understanding question or need help building your solution, check out our user forum.

• Create a high-quality issue:

  • Give enough context so that a person who doesn't know your project can understand your request
  • Be concise, only add what's needed to understand the core of the request
  • If you raise a bug report, describe the steps to reproduce the problem
  • Specify your environment (e.g. Fluxnova version, Fluxnova modules you use, ...)
  • Provide code. For a bug report, create a test that reproduces the problem. For feature requests, create mockup code that shows how the feature might look like. Fork our unit test Github template to get started quickly.** Needs To Be Reviewed **

You can contribute code that fixes bugs and/or implements features. Here is how it works:

1. Select an issue that you would like to work on. Have a look at our Project Board or the issues lists for the individual projects, e.g. Fluxnova-BPM-Platform Issues if you need inspiration. Be aware that some of the issues need good knowledge of the surrounding code.
2. Create a fork of the project to contribute from. Create a feature branch in your fork to hold your changes.
3. Check your code changes against our contribution checklist
   1. For large changes, open a draft PR before you have finished your implementation to get feedback.
4. Create a pull request.

We manage issues for the multiple Fluxnova projects through our Project Board. You can find the full list of FINOS hosted Fluxnova projects here.

Currently, not all Fluxnova packages on FINOS are public. To build fluxnova-bpm-platform, you must first clone and build all dependent repositories locally. Once all packages are public, you will be able to build fluxnova-bpm-platform directly without building dependencies locally.

• Java 17+
• Maven 3.8+
• Git

1. Clone and Build fluxnova-release-parent Repository

   This repository contains the parent POM used by other Fluxnova projects.

   git clone https://github.com/finos/fluxnova-release-parent
   cd fluxnova-release-parent
   mvn clean install -o

2. Clone and Build fluxnova-bpm-release-parent Repository

   This repository is the next-level parent POM, used by downstream projects.

   git clone https://github.com/finos/fluxnova-bpm-release-parent
   cd fluxnova-bpm-release-parent
   mvn clean install -o

3. Clone and Build fluxnova-feel-scala Repository

   This repository is a dependency for fluxnova-bpm-platform.

   git clone https://github.com/finos/fluxnova-feel-scala
   cd fluxnova-feel-scala
   # To skip tests (recommended for adopters only, contributors should always run tests):
   mvn clean install -DskipTests -DskipITs -o
   
   # To run all tests:
   mvn clean install -o

4. Clone and Build fluxnova-bpm-platform Repository

   Finally, build the main project. You can skip tests or run them as needed.

   git clone https://github.com/finos/fluxnova-bpm-platform
   cd fluxnova-bpm-platform
   # To skip tests:
   mvn clean install -DskipTests -DskipITs -o
   
   # To run all tests:
   mvn clean install -o

• The -o flag enables Maven offline mode, so it uses dependencies from your local .m2/repository/org/fluxnova directory.
• Artifacts from each build will be stored in your local Maven repository and used by subsequent builds.
• Once all Fluxnova dependencies are public, you can build fluxnova-bpm-platform directly without building the other repositories locally.

We use labels to mark and group our issues for easier browsing. We define the following label prefixes:

• bug: Labels that suggests something isn't working.
• documentation: Labels that define need for improvements or additions to documentation.
• duplicate: Label that refers to issue or pull request already existing.
• enhancement- Labels for new feature or request.
• good first issue: Label for newcomers.
• help wanted : Label suggesting extra attention is needed.
• invalid- Labels suggesting that doesn't seem right.
• question: Label if further information is requested.
• refactor : Label for refactoring to fluxnova after initial fork.
• security : Label to tag for the security issue.
• sync : Label for syncing repos with original fork.
• wontfix : Label to suggest this will not be worked on. The fluxnova-bpm-platform project uses GitHub Actions for automated CI/CD on FINOS. This workflow builds, tests, and deploys the project.

• Automatic Triggers:
  The workflow runs automatically on every push to the main branch and on every pull request.
• Manual Trigger:
  You can manually trigger the workflow from the GitHub Actions tab using the "Run workflow" button.
  When using this manual trigger (workflow_dispatch), you can select which branch to build.

1. Checkout Repository:
   Checks out the latest code from the selected branch.
2. Java Setup:
   Sets up the required Java version.
3. Git Configuration:
   Configures Git for the workflow environment.
4. Set Project Version:
   Sets the Maven project version.
5. Download Dependencies:
   Resolves and downloads all Maven dependencies and plugins.
6. Build and Deploy:
   Builds the project and deploys artifacts to GitHub Packages.
7. Run Tests:
   Runs unit and integration tests in separate jobs.

The deployment of artifacts to GitHub Packages is configured in the root pom.xml using the <distributionManagement> and <repositories> tags.

• <distributionManagement>:
  Specifies where Maven should deploy release and snapshot artifacts. For this project, both releases and snapshots are deployed to GitHub Packages.

• <repositories>:
  Lists the Maven repositories (including GitHub Packages for all Fluxnova dependencies) from which dependencies are resolved during the build.

Example configuration in the root pom.xml:

<repositories>
  <repository>
    <id>fluxnova-bpm-platform</id>
    <url>https://maven.pkg.github.com/finos/fluxnova-bpm-platform</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  <repository>
    <id>fluxnova-feel-scala</id>
    <url>https://maven.pkg.github.com/finos/fluxnova-feel-scala</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  <repository>
    <id>fluxnova-bpm-release-parent</id>
    <url>https://maven.pkg.github.com/finos/fluxnova-bpm-release-parent</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  <repository>
    <id>fluxnova-release-parent</id>
    <url>https://maven.pkg.github.com/finos/fluxnova-release-parent</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

<distributionManagement>
<repository>
   <id>fluxnova-bpm-platform</id>
   <name>GitHub Fluxnova Maven Packages</name>
   <url>https://maven.pkg.github.com/finos/fluxnova-bpm-platform</url>
</repository>
<snapshotRepository>
   <id>fluxnova-bpm-platform</id>
   <name>GitHub Fluxnova Maven Packages</name>
   <url>https://maven.pkg.github.com/finos/fluxnova-bpm-platform</url>
</snapshotRepository>
</distributionManagement>

An entire repository can then be built by running mvn clean install in the root directory. This will build all sub modules and execute unit tests. Furthermore, you can restrict the build to just the module you are changing by running the same command in the corresponding directory. Check the repository's or module's README for additional module-specific instructions. The webapps module requires NodeJS. You can exclude building them by running mvn clean install -pl '!webapps,!webapps/assembly,!webapps/assembly-jakarta'.

When building on GitHub Actions, you do not need to build dependent projects locally. All dependencies are already built and published to GitHub Packages from their respective repositories. The workflow uses the GH_TOKEN (a GitHub Personal Access Token) to access these packages securely.

• Go to the Packages section of the repository on GitHub to view published artifacts.
• These packages can be used as dependencies in other projects via GitHub Packages.

You can run Fluxnova in two modes: Tomcat and Spring Boot.

1. After a successful build, extract the Tomcat distribution archive:

   unzip distro/tomcat/distro/target/fluxnova-bpm-tomcat-0.0.1-SNAPSHOT.zip

2. Navigate to the extracted folder:

   cd fluxnova-bpm-tomcat-0.0.1-SNAPSHOT

3. Start the Fluxnova Tomcat server:

   sh start-fluxnova.sh

4. Access the Fluxnova Monitoring at http://localhost:8080/fluxnova/app/monitoring/default/#/dashboard

1. After a successful build, extract the Spring Boot distribution archive:

   unzip distro/run/distro/target/fluxnova-bpm-run-0.0.1-SNAPSHOT.zip

2. Navigate to the extracted folder:

   cd fluxnova-bpm-run-0.0.1-SNAPSHOT

3. Start the Spring Boot server:

   sh start.sh

4. Access the Fluxnova Monitoring at http://localhost:8080/fluxnova/app/monitoring/default/#/dashboard

In order to show us your code, you can create a pull request on Github. Do this when your contribution is ready for review, or if you have started with your implementation and want some feedback before you continue. It is always easier to help if we can see your work in progress.

A pull request can be submitted as follows:

1. Fork the Fluxnova repository you are contributing to

2. Commit and push your changes to a branch in your fork

3. Submit a Pull Request to the Fluxnova repository. As the base branch (the one that you contribute to), select main. This should also be the default in the Github UI.

4. In the pull request description, reference the github issue that your pull request addresses.

Before submitting your pull request for code review, please go through the following checklist: ** Wiki Pages are missing. Needs To Be Reviewed **

1. Is your code formatted according to our code style guidelines?
   • Java: Please check our Java Code Style Guidelines. You can also import our template and settings files into your IDE before you start coding.
   • Javascript: Your code is automatically formatted whenever you commit.
2. Is your code covered by unit tests?
   • Ask us if you are not sure where to write the tests or what kind of tests you should write.
   • Java: Please follow our testing best practices.
   • Have a look at other tests in the same module for how it works.
   • In rare cases, it is not feasible to write an automated test. Please ask us if you think that is the case for your contribution.
3. Do your commits follow our commit message conventions?
4. Does your code use the correct license headers?

All contributors must have a contributor license agreement (CLA) on file with FINOS before their pull requests will be merged. Please review the FINOS contribution requirements and submit (or have your employer submit) the required CLA before submitting a pull request.

The messages of all commits must conform to the style:

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

<body>

<footer>

Example:

feat(engine): Support BPEL

- implements execution for a really old standard
- BPEL models are mapped to internal ActivityBehavior classes

related to #123

Have a look at the commit history for real-life examples.

One of the following:

• feat (feature)
• fix (bug fix)
• docs (documentation)
• style (formatting, missing semi colons, �)
• refactor
• test (when adding missing tests)
• chore (maintain)

The scope is the module that is changed by the commit. E.g. engine in the case of https://github.com/finos/fluxnova-bpm-platform/commits/main/engine.

A brief summary of the change. Use imperative form (e.g. implement instead of implemented). The entire subject line shall not exceed 70 characters.

A list of bullet points giving a high-level overview of the contribution, e.g. which strategy was used for implementing the feature. Use present tense here (e.g. implements instead of implemented). A line in the body shall not exceed 80 characters. For small changes, the body can be omitted.

Must be related to <ticket> where ticket is the ticket number, e.g. CAM-1234. If the change is related to multiple tickets, list them in a comma-separated list such as related to CAM-1234, CAM-4321.

Optionally, you can reference the number of the GitHub PR from which the commit is merged. The message footer can then look like related to <ticket>, closes #<pr_number> such as related to CAM-1234, closes #567.

Every source file in an open-source repository needs to contain the following license header at the top, formatted as a code comment: ** License. Needs To Be Reviewed **

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 (check other files). If you use our IDE settings, it will be generated automatically when you create new .java files. You can also add it by running mvn clean install -Plicense-header-check in the module that you have changed. This command also re-formats any incorrectly formatted license header.

Contributions that do not contain valid license headers cannot be merged.

We usually check for new community-submitted pull requests once a week. We will then assign a reviewer from our development team and that person will provide feedback as soon as possible.

Note that due to other responsibilities (our own implementation tasks, releases), feedback can sometimes be a bit delayed. Especially for larger contributions, it can take a bit until we have the time to assess your code properly.

During review we will provide you with feedback and help to get your contribution merge-ready. However, before requesting a review, please go through our contribution checklist.

Once your code is merged, it will be shipped in the next alpha and minor releases. We usually build alpha releases once a month and minor releases once every six months. If you are curious about the exact next minor release date, check our release announcements page. ** Needs To Be Reviewed **

The project community consists of Contributors and Maintainers:

• A Contributor is anyone who submits a contribution to the project. (Contributions may include code, issues, comments, documentation, media, or any combination of the above.)
• A Maintainer is a Contributor who, by virtue of their contribution history, has been given write access to project repositories and may merge approved contributions.
• The Lead Maintainer is the project's interface with the FINOS team and Board. They are responsible for approving quarterly project reports and communicating on behalf of the project. The Lead Maintainer is elected by a vote of the Maintainers.

Anyone is welcome to submit a contribution to the project. The rules below apply to all contributions. (The key words "MUST", "SHALL", "SHOULD", "MAY", etc. in this document are to be interpreted as described in IETF RFC 2119.)

• All contributions MUST be submitted as pull requests, including contributions by Maintainers.
• All pull requests SHOULD be reviewed by a Maintainer (other than the Contributor) before being merged.
• Pull requests for non-trivial contributions SHOULD remain open for a review period sufficient to give all Maintainers a sufficient opportunity to review and comment on them.
• After the review period, if no Maintainer has an objection to the pull request, any Maintainer MAY merge it.
• If any Maintainer objects to a pull request, the Maintainers SHOULD try to come to consensus through discussion. If not consensus can be reached, any Maintainer MAY call for a vote on the contribution.

The Maintainers MAY hold votes only when they are unable to reach consensus on an issue. Any Maintainer MAY call a vote on a contested issue, after which Maintainers SHALL have 36 hours to register their votes. Votes SHALL take the form of "+1" (agree), "-1" (disagree), "+0" (abstain). Issues SHALL be decided by the majority of votes cast. If there is only one Maintainer, they SHALL decide any issue otherwise requiring a Maintainer vote. If a vote is tied, the Lead Maintainer MAY cast an additional tie-breaker vote.

The Maintainers SHALL decide the following matters by consensus or, if necessary, a vote:

• Contested pull requests
• Election and removal of the Lead Maintainer
• Election and removal of Maintainers

All Maintainer votes MUST be carried out transparently, with all discussion and voting occurring in public, either:

• in comments associated with the relevant issue or pull request, if applicable;
• on the project mailing list or other official public communication channel; or
• during a regular, minuted project meeting.

Any Contributor who has made a substantial contribution to the project MAY apply (or be nominated) to become a Maintainer. The existing Maintainers SHALL decide whether to approve the nomination according to the Maintainer Voting process above.

This document MAY be amended by a vote of the Maintainers according to the Maintainer Voting process above.