# FINOS Community > FINOS Community documentation around governance, development infrastructure and best practices of our Community This file contains all documentation content in a single document following the llmstxt.org standard. ## Collaboration Infrastructure FINOS leverages many services offered by [GitHub.com](https://github.com), which are documented in the [Collaboration Use Cases on GitHub](#collaboration-use-cases-on-github) and [other collaboration use cases](#other-collaboration-use-cases) sections below. In order to contribute to and collaborate on a FINOS project, you will need to [create a GitHub.com account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github) and meet the FINOS [contribution requirements](/docs/governance/Software-Projects/contribution-compliance-requirements) for your project (for example DCO or CLA); this document will walk you through access control and permissions that are enforced on FINOS GitHub properties. :::important If you're a maintainer of a FINOS hosted project and need infrastructure that is not documented here, please [contact help@finos.org](mailto:help@finos.org), the FINOS Staff will be happy to assist you. ::: ### GitHub Account Setup In order to configure your GitHub access, it is necessary to: 1. [Create an account on GitHub.com](https://help.github.com/en/github/getting-started-with-github/signing-up-for-a-new-github-account) 2. [Setup a Git client locally](https://help.github.com/en/github/getting-started-with-github/set-up-git) 3. Ensure that the Git client is configured with your `@users.github.com` email address (you can use `git config --list | grep user.email` command). If you use another email address, you may incur in one of the following issues: 1. Your corporate firewall blocks Git activity, unless you have signed in with an `@` email address. 2. GitHub forces you to set the email address as public, or it would reject push operations with the error `push declined due to email privacy restrictions`. ### Access Control All repositories managed by the Foundation are public. As a result, anyone can: 1. Checkout the source code 2. Consume any artifact produced by a Project 3. Access [FINOS Kanban boards](https://github.com/orgs/finos/projects) 4. Use GitHub Issues to contribute to the discussion (a GitHub account is required) Any GitHub user who meets [FINOS contribution requirements](/docs/governance/Software-Projects/contribution-compliance-requirements) for their project (such as DCO or CLA coverage) can also: 1. [Become a member of the FINOS GitHub Organization](#becoming-github-finos-organization-member) 2. Submit a code change via [Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) [FINOS uses GitHub Teams](https://github.com/orgs/finos/teams) to manage each project's committer team. These teams are the only groups allowed to make direct changes to project repositories. Below is a recap of who can do what. | Who | GH role | What | |--- | :----------| :----------| | Anyone | None | Checkout the source code | | | | Consume any artifact produced by a Project | | | | Access FINOS issue boards | | Any GitHub user | Read | Fork repository | | | | Submit a code change via Pull Request (flagged by EasyCLA) | | | Use GitHub Issues to contribute to the discussion | | GitHub user covered by [CLA](/docs/governance/Software-Projects/easycla) | Read | Become a member of the GitHub FINOS Organization | | | | Submit a code change via Pull Request (validated by the EasyCLA) | | FINOS Staff | Triage | Issue/PR Triage | | | | Administration tasks | | | | Monitoring | | Project Maintainer (GitHub User) | Maintain | Approve Pull Requests | | | | Manage releases | | | | Manage roadmap | | | | Manage website and other project infrastructure | | | | Anything granted by the GitHub `Maintain` permission | | Lead Maintainer (GitHub User) | Maintain | Point of contact with FINOS Staff | Checkout the [GitHub docs around roles and permissions](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#repository-access-for-each-permission-level) to know more about entitlements. #### GitHub Member VS FINOS Member Please note, [FINOS Members](https://finos.org/members) are organizations that provide industrial and financial support to the FINOS through their platinum, gold, and/or silver [membership fees](https://finos.org/membership-benefits), and through their participation in the [FINOS Governing Board](https://www.finos.org/governing-board). [Members of the FINOS GitHub Organization](https://github.com/orgs/finos/people) are individuals, represented by a [GitHub Profile](https://docs.github.com/en/github/setting-up-and-managing-your-github-profile/about-your-profile) and a signed FINOS [Contributor License Agreement (CLA)](/docs/governance/Software-Projects/easycla). #### Becoming GitHub FINOS Organization member Assuming that you have read our [Contribution Requirements](/docs/governance/Software-Projects/contribution-compliance-requirements) and have the appropriate contributor coverage for your project (for example a [CLA](/docs/governance/Software-Projects/easycla) where your repository uses CLA), you can request to be invitated to [FINOS GitHub Organization](https://github.com/orgs/finos/people) by emailing your GitHub username to [help@finos.org](mailto:help@finos.org). #### Public VS Private Membership Any GitHub FINOS Organization member can decide whether to publish her/his affiliation with FINOS or not; given that the employer doesn't restrict such action, we welcome any of our member to set to Public the Organization visibility: 1. Access https://github.com/orgs/finos/people 2. Search for your name or GitHub username 3. Open the dropdown close to Private 4. Select Public visibility #### Teams Given that all project contributors have the ability to follow the standard GitHub (Pull Request) development workflow, the only actors that need to have any entitlement on GitHub repositories are maintainers. We use GitHub Teams to manage that, where: 1. Lead Maintainers have the ability to add new maintainers (aka GitHub Team maintainer) 2. Project maintainers can vote to add/remove team members 3. the project maintainers team have (GitHub) `Maintain` permission across all project (GitHub) repositories. #### Useful links - [About permissions on GitHub](https://help.github.com/en/github/getting-started-with-github/access-permissions-on-github#organization-accounts) - [About GitHub Teams](https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/about-teams) - [Other GitHub guides](https://guides.github.com/) ### Collaboration use cases on GitHub #### Code hosting Code in the Foundation is hosted exclusively on [https://github.com/finos](https://github.com/finos); each FINOS project code can be spread across different repositories, you can check the [FINOS Landscape](https://landscape.finos.org) to have an overview of all FINOS initiatives and the GitHub repositories that host its code. ##### Repository setup The Foundation encourages the thoughtful design of projects such that they result in multiple functionally independent, decoupled libraries. One of the ways this can be done is by using multiple GitHub repositories per project (one per decoupled library). If you have an existing project and you'd like to add more repositories to it, you should have all permissions to be able to do it. If you'd like any advanced configuration for your repository, build or release process, please reach out to [help@finos.org](mailto:help@finos.org). Although GitHub doesn't directly support the concept of a "project" (a group of related repositories), the Foundation keeps track of this information, and uses it in our [landscape](https://landscape.finos.org) and [metrics](https://metrics.finos.org) dashboards. ##### Building and testing A build pipeline converts source code into deployable artifacts produced by the project team and hosted in GitHub. Reliable builds are essential because they can trigger automated tasks such as versioning, testing, quality checks, and compliance reporting. A working build process is key to implement more automated processes, such as release, Continuous Integration and automated deployments; it is also a requirement for [project Graduation](/docs/governance/lifecycle-stages/graduated). ##### Versioning Versioning is the process to establish a format to a project version and the rules to update it, preferably integrating with automated build and release systems; the Foundation mandates the use of [Semantic Versioning](https://semver.org/) ("semver") throughout a project's lifecycle: - for Incubating projects, version numbers must be less than 1.0.0 - for [Graduated](/docs/governance/lifecycle-stages/graduated) projects, version numbers can be 1.0.0 or greater Every project team is encouraged to define specific criteria by which the MAJOR, MINOR and PATCH components of the semver scheme will be used (keeping in mind the general guidelines semver itself mandates), since this helps to provide clarity to consumers. ##### Release The release process allows to publish deployable units into a publicly available artifact repository, by invoking the build process and applying version control to increment the project's version; the Foundation collects guides and best practices on how to release a project, depending on the language and eco-system of choice. ##### Best practices ###### Avoid direct changes to GitHub repositories - use Pull Requests Making direct changes to repositories is not recommended, for teams bigger than 1, for few reasons, including: 1. Direct commits are not validated, as they cannot be blocked (ie, if [CLA](/docs/governance/Software-Projects/easycla) is not in place) 2. Pull Requests allow to have a conversation with the team 3. Pull Requests tend to have a more thorough validation pipeline #### Accepting Code Contributions Project teams are required to review contributions from non-committer community members (i.e. PRs) in a timely fashion. While this does not mean that all such contributions need to be accepted, they must be reviewed conscientiously and only rejected if there are legitimate reasons to do so. Those reasons must be clearly documented in the PR at the time of rejection, and any resubmissions re-reviewed in good faith. In addition to the usual code-level checks a project team may choose to perform on contributions (for code quality, roadmap alignment, etc.), it is also critically important that the legal requirements of the Foundation are met. This involves: 1. Confirming that the person providing the contribution has a Contributor Licensing Agreement in place with the Foundation (though [EasyCLA](/docs/governance/Software-Projects/easycla) will run an automatic scan of all Pull Requests). 2. Confirming that their change doesn't introduce new code or dependencies that are incompatible with the Apache Software License. The Foundation's project infrastructure automatically checks for CLA compliance for pull requests only. Unfortunately it's not currently possible to check for CLA compliance of commits that are directly pushed to a master branch by a committer (this is a GitHub limitation). For that reason, we strongly recommend that project teams do not add new project team members until they've verified that those contributors have a CLA in place with the Foundation. In the meantime, you can encourage contributors to fork your project and contribute via pull requests, until such time as you've confirmed their CLA status with the Foundation's legal counsel. Confirming that contributions haven't introduced incompatibly licensed code is inherently build tool specific, and so we are unable to provide instructions that cover all possible development setups. Check the list of code validation tools available to FINOS hosted projects. #### Managing Issues [**GitHub Issues**](https://guides.github.com/features/issues/) provides a simple and flexible way to track task lists; issues can also include list of checkboxes, as shown in the image. Labels can be useful to add meta information to tasks, like type, audience and more. ##### Issue Templates When creating a new issue, it is possible to guide users via Issue Templates, which allow to: 1. Choose an issue type from a list; at FINOS, we start providing 3 templates: bugs, feature requests and support questions (check the project blueprint below) 2. Define a template for the issue content (ie, abstract, expected result, actual result) ##### Issue Labels Labels are very helpful to manage issues; each repository can define its own taxonomy, though it is helpful to enforce a common list of labels, so that the experience of using GitHub Issues across different repositories and projects is the same. It is also handy when using GitHub boards that link to multiple repositories. ``` - Priorities - #ff0000 - prio-high - High priority - prio-low - Low priority - prio-medium - Medium priority - Contribution hints - #5319e7 - good first issue - A good first issue to start contributing - help wanted - Issue status - #a2e8e6 - on hold - Tasks not executed until further notice - feature writing - Grooming and feature writing needed - ready for dev - This item is ready for development - Types - #53c43c - docs - Related to documentation - question - Further information is requested - meeting - If an issue describes a meeting agenda or minutes - vote - If an issue describes a vote - Topics - #ffd4b7 - github - GitHub related topic - docusaurus - Docusaurus related topic ``` #### Project Releases The easiest way to define roadmaps in GitHub is using [**Milestones**](https://guides.github.com/features/issues/), which allow to group issues together and associate a title, description and due date. As a complement or alternative, [**GitHub project boards**](https://help.github.com/en/articles/about-project-boards) can be used to define a Kanban (or "flow") of activities across a list of predefined states, which can be mapped to the milestones of a roadmap. #### Project Website FINOS Projects may need a Wiki in order to collaboratively edit and publish content related with general documentation, team composition, meeting information, how to get in touch and other useful info. You can read more on the project documentation page. #### Conversations In order to track threaded conversations - among FINOS Project / SIG team members, external collaborators and consumers - it is possible to use [GitHub Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues), with the following limitations: 1. The scope of the conversations is always public, whereas there may be sensitive conversations across project leaders that may require to be confidential 2. Issue comments are flat, although mentions and quoting can be used to follow multiple conversation threads. #### [DEPRECATED] GitHub Team Discussions :::important The Team Discussion feature was [deprecated on February 8th 2023](https://github.blog/changelog/2023-02-08-sunset-notice-team-discussions/) ::: A more advanced way is to use [GitHub Team Discussions](https://docs.github.com/discussions): 1. Can be created as private, which are accessible only by team members 2. Can be created as public to all GitHub FINOS org members 3. Cannot be created at public to non FINOS member or unauthenticated visitors, so GitHub Issues is the only option for that. #### FINOS Slack The [FINOS Slack](https://finos-lf.slack.com/) brings the FINOS Community together in a Slack Workspace dedicated to **_"public"_** conversations and made available to all FINOS Projects and Special Interest Groups. [![](https://img.shields.io/badge/slack-@finos/community-green.svg?logo=slack)](https://finos-lf.slack.com/messages/finos-community/) Join the FINOS Project, SIG and wider community conversation in the FINOS Community Slack. If you are an employee of a [FINOS Member](https://finos.org/members), corporate firewall restrictions allowing, you should be able to self-subscribe at https://finos-lf.slack.com/signup. If you are not a FINOS Member or have any trouble joining, please email to [help@finos.org](mailto:help@finos.org) with your desired email address and we'll set you up. The FINOS Community wide channel on Slack is reachable directly at https://finos-lf.slack.com/messages/finos-community/. We warmly encourage existing community contributors to invite their peers to join the collaboration and the open source fun :) FINOS Project and SIG Leads, please email to [help@finos.org](mailto:help@finos.org) to create a Slack Channel for your FINOS Project or Special Interest Group. All participants in the FINOS Slack are subject to the [LF Antitrust Policy](https://www.linuxfoundation.org/legal/antitrust-policy), the [FINOS Community Code of Conduct](https://www.finos.org/code-of-conduct) and all other [FINOS policies](/docs/governance/#policies). It's extremely important that all participants in the FINOS Slack do not participate in any activities that are prohibited under applicable US state, federal or foreign antitrust and competition laws. #### Voting FINOS Governance processes require voting at different levels (and publicly available), including but not limited to: 1. Project Maintainers vote for accepting new members to their teams 2. Project Maintainers vote to manage releases and other decide on any other decisions GitHub Issues can provide an easy platform to vehicle this process: 1. The person casting the vote opens a GitHub Issue. The following items must be filled/reviewed, before circulating the issue URL: a. Title and description of the vote; use the [VOTE] prefix in the issue title, to help issue browsing and discoverability b. Add the vote label c. List of users who have the right to a binding vote, typically project maintainers 2. Everyone can vote the issue, until the vote is open: a. Those with a GitHub account can simply react to the issue (see image to the right) b. Those without a GitHub account can react via email (using any public FINOS list) 3. The person casting the vote counts reactions and reports the following data in a issue comment: a. Total votes (add links to email web history for each email vote, if any) b. Binding votes (Approve, Deny, Abstained) c. Result ##### Project setup A project needs: 1. A Github repository 2. The `vote` issue label defined 3. Issue template `.github/ISSUE_TEMPLATE/Vote.md` defined #### Meeting Minutes Meetings are one of the most used collaboration channels at FINOS, and minutes are very important, as they provide transparency across all project activities and decisions. Follow the [Meeting Procedures](/docs/governance/meeting-procedures) for scheduling in LFX PCC, agendas, minutes, and AI summaries. Create a GitHub Issue for each meeting using the [Meeting template provided by FINOS](https://github.com/finos/software-project-blueprint/issues/new?template=meeting_minutes.yml). The issue is the public agenda and minutes record; do not use it to track attendance. - *Prior to the meeting* - the meeting leader creates a new GitHub Issue using the meetings issue template, a `[MEETING]` title prefix, and the `meeting` label, then circulates the issue as the agenda. - *At the beginning of the meeting* - the meeting leader posts the issue URL on the meeting chat. - *After the meeting* - review the LFX PCC Zoom AI summary, **anonymize** it, **publish** it, add the published summary URL to the issue, and close the issue. ##### Project setup A project needs: 1. A Github repository 2. The meeting leader must have at least `Write` access to the repository 3. The `meeting` issue label defined 4. Issue template [`.github/ISSUE_TEMPLATE/meeting_minutes.yml`](https://github.com/finos/software-project-blueprint/blob/main/.github/ISSUE_TEMPLATE/meeting_minutes.yml) defined #### Security Scanning In order to consolidate processes and tools around security vulnerabilities management, FINOS have shared a [guidelines around responsible disclosure for security vulnerabilities](/docs/governance/Software-Projects/cve-responsible-disclosure) and tools that can be used to automate code scanning, you can read more on the code validation page. FINOS also provides a collection of Github Action that can be used on your repositories, checkout the [code scanning project](https://github.com/finos/code-scanning). #### FINOS Project blueprint [Project blueprint](https://github.com/finos/software-project-blueprint) is a FINOS project that provides a template for new or existing repositories; it includes: 1. A [README.md template](https://github.com/finos/software-project-blueprint/blob/master/README.template.md), with a suggested structure of content 2. A [NOTICE template](https://github.com/finos/software-project-blueprint/blob/master/NOTICE), required by FINOS bylaws 3. A [LICENSE template](https://github.com/finos/software-project-blueprint/blob/master/LICENSE), required by FINOS bylaws 4. A [Code of Conduct](https://github.com/finos/software-project-blueprint/blob/master/.github/CODE_OF_CONDUCT.md) template, required by FINOS bylaws 5. [Contributing guidelines](https://github.com/finos/software-project-blueprint/blob/master/CONTRIBUTING.md), required by FINOS bylaws 6. A [MAINTAINERS.md](https://github.com/finos/software-project-blueprint/blob/main/MAINTAINERS.md) file in the repository root, listing the current project maintainers 7. A [SECURITY.md](https://github.com/finos/software-project-blueprint/blob/main/SECURITY.md) file in the repository root, linking to the [FINOS Security Vulnerabilities Responsible Disclosure Policy](https://community.finos.org/docs/governance/software-projects/cve-responsible-disclosure/) 8. Issue templates for bugs, feature requests and support questions , [defined in the `.github` folder](https://github.com/finos/software-project-blueprint/tree/master/.github/ISSUE_TEMPLATE) Placeholders use `{UPPER_SNAKE_CASE}` tokens throughout the blueprint. ##### Creating a new repository Anyone can use the Project blueprint repository, simply accessing [https://github.com/finos/software-project-blueprint](https://github.com/finos/software-project-blueprint) and pressing the `Use this template` button and following instructions. The main `README.md` file contains instructions on how to replace placeholders across all blueprint files. ##### Aligning existing repository with project blueprint There is no automated way to align an existing repository with the project blueprint structure, therefore it must be done manually, going through the blueprint items listed above and copy/paste content across repositories. ##### Built-in documentation website The project blueprint comes with a pre-definite website that is built using Docusaurus (3.x) and served via Netlify to a custom finos.org subdomain. Getting started is quite simple: 1. Make sure that your GitHub repository includes the `docs/` and `website/` folder from the [software-project-blueprint](https://github.com/finos/software-project-blueprint) 2. Add [`osv-scanner.toml`](https://github.com/finos/software-project-blueprint/blob/main/website/osv-scanner.toml) to the website root. This helps keep project health accurate. 3. Read our getting started guide to understand more about Docusaurus ##### How to use this blueprint 1. Visit https://github.com/finos/software-project-blueprint 2. Click on `Use this template` and follow GitHub's instructions. 3. In your new repository, copy `README.template.md` to `README.md` (replacing this file). 4. Search and replace the following tokens across the copied files: | Token | Replace with | | ----- | ------------ | | `{PROJECT_NAME}` | The name of the FINOS project, e.g. `Open Developer Platform` | | `{PROJECT_SLUG}` | The GitHub repository name, e.g. `software-project-blueprint` | | `{PROJECT_URL}` | The GitHub repository URL, e.g. `https://github.com/finos/software-project-blueprint` | | `{PROJECT_MAILING_LIST}` | The project mailing list address, if any | | `{YYYY}` | The year you started working on the code | | `{CURRENT_YEAR}` | The current year | | `{NAME_OF_COPYRIGHT_OWNER}` | The copyright owner of the code (typically you or your employer) | | `{EMAIL_OF_COPYRIGHT_OWNER}` | The email address of the copyright owner of the code (if known) | | `{OTHER_NOTICES}` | Additional NOTICE attributions required by dependencies, or remove this token | 5. Open the `NOTICE` file and either remove `{OTHER_NOTICES}` or [add attributions if required by your code's dependencies](/docs/governance/Software-Projects/license-categories). 6. Open `README.md` and complete the content as appropriate for your project. 7. Open `MAINTAINERS.md` and add maintainer names, GitHub usernames, and, optionally, email addresses. 8. Add the [Apache license header to all of your source files](https://www.apache.org/licenses/LICENSE-2.0.html#apply). 9. (optional) Remove the `EASYCLA_CHANGEME.md`, `.node-version`, and `renovate.json` files, if not applicable to your project. 10. (optional) Remove the `docs/` and `website/` folders + the `netlify.toml` file, if you do not need a project documentation website. 11. Commit and push all of your changes. #### Automated and continuous quality scanning FINOS provides some examples on https://github.com/finos/code-scanning to run continuous code scanning activities. More tools are also documented on the code validation page. ### Other collaboration use cases #### Meeting Management FINOS project and SIG maintainers schedule their own Zoom meetings in the Linux Foundation [LFX Project Control Center (PCC) Meetings](https://docs.linuxfoundation.org/lfx/project-control-center/v2-latest-version/collaborations/meetings) tool. Email [help@finos.org](mailto:help@finos.org) to be granted PCC access to your project, then follow the [FINOS Meeting Procedures](/docs/governance/meeting-procedures). #### Mailing Lists (Google Groups) The Foundation provides mailing lists via the [Google Groups service](https://groups.google.com/a/finos.org/forum/#!myforums). Email, as a lowest common denominator communication channel, is one of the best ways to reach the broadest cross-section of the community as possible. The FINOS mailing lists have a fairly low amount of collaboration, as GitHub.com Issues and Discussions are normally used instead; they're mostly used for announcements and notifications, to stay in touch with marketing, community and project updates. Checkout the [list of FINOS Google Groups](/docs/journey/engage). ##### Email Best Practices - Keep it clean - many members of the community participate from their place of employment, so please use professional tone and language at all times. - Treat people with respect and consideration - specifically, ensure you're familiar with the [code of conduct](https://www.finos.org/code-of-conduct). - Be helpful - be willing to jump in to answer questions. Even if you aren't 100% sure of the answer, posting your understanding can help unlock a deeper conversation (and if you're unsure, briefly saying so is a good idea). - Stay calm - the written word is always open to interpretation, so give people the benefit of the doubt and try not to let emotions get out of control. - Be patient - people with the appropriate skills might not be around the moment you ask a question. New community members will be asking "beginner" questions that may have already been answered previously - be gentle and polite in helping them navigate the Foundation's content. - Minimize "walls of text" - avoid emails containing large blocks of text. A worthy aspiration is to try to craft emails that fit on a smart phone screen without swiping. - Prefer public mailing lists for all email communication - chances are that someone else in the community will be interested in the topic you're discussing, and by leveraging public mailing lists you create the opportunity for them to find that content themselves. - Don't use email attachment - Many banks silently delete emails containing certain types of file attachment - notably executables (EXE files, etc.), source code files (JS files, etc.), and archive files (ZIP files, etc.). For this reason we recommend using file attachments sparingly, limiting the use of archive files when sending attachments, and trying to stick to "safe" (content only) file formats such as PDF, Word, Powerpoint, etc. #### Contacting the FINOS team If a project team wishes to contact the FINOS team the can reach out via the [help@finos.org](mailto:help@finos.org). #### Private or Sensitive Information In the rare event that a project team wishes to discuss private or sensitive matters, they can reach out to individual FINOS team members or at [legal@finos.org](mailto:legal@finos.org). Please note that the FINOS team is also responsible for handling Community Code of Conduct violations, so please see that page for details on reporting such incidents. --- ## Code Climate | | | |--- | :---| | **Name** | CodeClimate | | **Status** | Delivered | | **Link** | [codeclimate.com](https://codeclimate.com) | | **Topics** | Quality | | **Languages** | Java, Javascript | [CodeClimate](https://codeclimate.com/) delivers automated code review for test coverage, complexity, duplication, security, style and more; several [languages and platforms](https://docs.codeclimate.com/docs/supported-languages-for-maintainability) are supported. Below are listed the main features that have been adopted by Foundation projects. 1. Integration with CI environments 2. Measures test coverage 3. Scans code for security vulnerabilities 4. Scans code for bad practices 5. Scans code for bugs Simply define a [.codeclimate.yml](https://docs.codeclimate.com/v1.0/docs/example-codeclimateyml) in the root of your project to get started. ### Request access Sign into [codeclimate.com](https://codeclimate.com/) using your GitHub credentials and configure your project from the dashboard. --- ## Coverity Scan | | | |--- | :---| | **Name** | Coverity | | **Status** | Delivered | | **Link** | [scan.coverity.com](https://scan.coverity.com) | | **Topics** | Security,Quality | | **Languages** | Java, Javascript, C#, Python | The [Coverity Scan](https://scan.coverity.com/) service was initiated with the U.S. Department of Homeland Security as the largest public-private sector research project in the world, focused on open source software quality and security; it is now a free service to the open source community. Below are listed the main CoverityScan features that have been adopted by Foundation projects. 1. Integration with CI environments 2. Scans code for security vulnerabilities 3. Scans code for bad practices 4. Scans code for bugs Please note that Coverity applies [frequency build limits](https://scan.coverity.com/faq#frequency); the build configuration (and/or branching strategy) must be adapted to avoid high submission rate. ### Request access CoverityScan provides a Github signup that grants access to a personal dashboard and register a new Github project. --- ## Code Validation In order to assess Security, Quality and Legal compliance of software hosted by the Foundation, project leads and committers can configure integrations with third-party systems that are provided by the Foundation; the result of these processes can be published in the project's documentation to improve the final consumer experience and when requesting activation. Below is the list of code validation systems currently available, across supported languages and validation features. ### Security vulnerabilities responsible disclosure Read the [FINOS security vulnerabilities responsible disclosure](/docs/governance/Software-Projects/cve-responsible-disclosure) document to know how security incidents are managed across FINOS projects. Use [WhiteSource](/docs/development-infrastructure/code-validation/whitesource) to configure your FINOS project for automated scanning. ### Matrix of validation features and supported languages | Features | C# | Clojure | Java | Javascript | Python | |--- | :---: | :---: | :---: | :---: | :---: | | **Legal compliance** | | Check libraries for problematic/undefined licenses | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | | Generates legal reports | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | | **Security** | | Scans code for security vulnerabilities | [FINOS Code Scanning](https://github.com/finos/code-scanning), [CoverityScan](coverityscan), [SonarCloud](sonarcloud) | [FINOS Code Scanning](https://github.com/finos/code-scanning) | [FINOS Code Scanning](https://github.com/finos/code-scanning), [CodeClimate](codeclimate), [CoverityScan](coverityscan), [SonarCloud](sonarcloud) | [FINOS Code Scanning](https://github.com/finos/code-scanning), [CodeClimate](codeclimate),[SonarCloud](sonarcloud) | [FINOS Code Scanning](https://github.com/finos/code-scanning) | | Check libraries for security vulnerabilities | [FINOS Code Scanning](https://github.com/finos/code-scanning), [WhiteSource](whitesource) | [FINOS Code Scanning](https://github.com/finos/code-scanning), [WhiteSource](whitesource) | [FINOS Code Scanning](https://github.com/finos/code-scanning), [WhiteSource](whitesource) | [FINOS Code Scanning](https://github.com/finos/code-scanning), [WhiteSource](whitesource) | [FINOS Code Scanning](https://github.com/finos/code-scanning), [WhiteSource](whitesource) | | **Quality** | | | | | | | Measures test coverage | [SonarCloud](sonarcloud) | | [CodeClimate](codeclimate),[SonarCloud](sonarcloud) | [CodeClimate](codeclimate), [SonarCloud](sonarcloud) | | | Check libraries for bugs | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | | Check libraries for outdated versions | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource)| [WhiteSource](whitesource) | | Check unused libraries | | | | | | | Check libraries for release activity | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | [WhiteSource](whitesource) | | Scans code for hacks and todos | | | | | | | Scans code for bad practices | [CoverityScan](coverityscan) | | [CodeClimate](codeclimate), [CoverityScan](coverityscan) | [CodeClimate](codeclimate) | | | Scans code for bugs | [CoverityScan](coverityscan) | | [CoverityScan](coverityscan) | | | ### Continuous validation FINOS provides a set of tools, specifically GitHub Apps and Actions, that enforce a continuous scanning across the FINOS GitHub repositories. #### CLA To help project leads validate external contributor's identity and capacity to contribute code to the Foundation please visit https://community.finos.org/docs/governance/Software-Projects/EasyCLA/ to know more about FINOS CLAs. #### Project compliance scan FINOS have developed a tool that scans all the GitHub repositories across all FINOS orgs and generates a report based on the following quality and compliance validations: - `has-admin` - One or more admin collaborators were found in this GitHub repository. FINOS Governance doesn't allow GitHub users to have Admin rights on repositories, therefore it must be removed. - `has-user` - One or more user collaborators were found in this GitHub repository. FINOS Governance only allows GitHub users to be added via Teams. Please remove it, therefore it must be removed. - `disabled-issues` - This GitHub repository does not have GitHub Issues enabled; make sure that there is a documented way to submit questions, feature requests and other communications to the project team. - `no-teams` - This GitHub repository does not grant permissions to any FINOS Team, although it should be configured to grant access to project maintainers defined as [GitHub Teams](https://github.com/orgs/finos/teams). Please email help@finos.org and coordinate changes to the repository access permissions. - `no-issue-templates` - This GitHub repository does not use issue templates; please check the [issue template blueprints](https://github.com/finos/software-project-blueprint/tree/master/.github/ISSUE_TEMPLATE). - `no-contributing` - `CONTRIBUTING.md` file is missing; check the [CONTRIBUTING.md template](https://github.com/finos/software-project-blueprint/blob/master/CONTRIBUTING.md). - `no-code-conduct` - `CODE_OF_CONDUCT.md` file is missing; check the [CODE_OF_CONDUCT.md template](https://github.com/finos/software-project-blueprint/blob/master/.github/CODE_OF_CONDUCT.md). - `notice-nok` - `NOTICE` file is incomplete; check line 4 of the [NOTICE template](https://github.com/finos/software-project-blueprint/blob/master/NOTICE). - `no-notice` - `NOTICE` file is missing; check the [NOTICE template](https://github.com/finos/software-project-blueprint/blob/master/NOTICE). - `no-readme` - `README.md` file is missing; check the [README.md template](https://github.com/finos/software-project-blueprint/blob/master/README.template.md). - `no-description` - This GitHub repository does not have a general description defined; the `Edit` button is seen when on the repositories main page, which is the `Code` tab. - `is-archivable` - This repository belongs to project `{{project-name}}` which is archived, therefore the GitHub repository is expected to be archived too. @finos-staff will get in touch with the project lead to sort it out. - `readme-nok` - `README.md` file is incomplete; check the [README.md template](https://github.com/finos/software-project-blueprint/blob/master/README.template.md) and make sure that `## Contributing` and `## License` sections exist. - `no-badge` - `README.md` file is missing the FINOS badge; check the [README.md template](https://github.com/finos/software-project-blueprint/blob/master/README.template.md) and make sure that it embeds one of SVG FINOS badges. - `wrong-badge` - Our internal records state that this project is in `{{project-state}}` state, whereas `README.md` states `{{readme-state}}`; make sure that `README.md` embeds the right FINOS badge. - `repo-not-on-file` - We don't have this repository on file. We will fix this issue on our side as soon as possible and keep you posted. - `no-whitesource` - WhiteSource configuration was not found; make sure that dependencies are scanned against security vulnerabilities. Read more on [the WhiteSource page](/docs/development-infrastructure/code-validation/whitesource). Code is publicly available on https://github.com/finos/metadata-tool, the command to invoke is `check-project-repos`. ##### Ignoring validations There may be corner cases, for example repositories that contain data don't need whitesource integration. In those cases, it is possible to define a `.finos-blueprint.json` file in the root folder, with the following structure: ``` { "ignore" : [ "no-whitesource", "readme-nok" ] } ``` ##### Exporting to CSV Here's a useful command to transform the metadata-tool JSON output in CSV. ``` cat finos-repo-validation.json| jq -r '.[] | [.org, .["repo-name"], .validations["has-admin"], .validations["has-user"], .validations["no-teams"], .validations["no-issues"], .validations["no-issue-templates"], .validations["no-contributing"], .validations["no-code-conduct"], .validations["notice-nok"], .validations["no-notice"], .validations["no-readme"], .validations["no-description"], .validations["is-archivable"], .validations["readme-nok"], .validations["no-badge"], .validations["wrong-badge"], .validations["repo-not-on-file"], .validations["no-whitesource"]] | @csv' ``` --- ## Sonar Cloud | | | |--- | :---| | **Name** | sonarcloud | | **Status** | Delivered | | **Link** | [sonarcloud.io](https://sonarcloud.io) | | **Topics** | Security, Quality | | **Languages** | Java, Javascript, C# | [SonarCloud](https://sonarcloud.io/) is a service operated by [SonarSource](https://www.sonarsource.com/), the company that develops and promotes open-source code quality products [SonarQube](https://www.sonarqube.org/) and [SonarLint](https://www.sonarlint.org/); SonarSource provides SonarCloud for open source projects, free of charge. Below are some of the most important features used by Foundation projects: 1. Integration with CI environments 2. Measures test coverage 3. Scans code for security vulnerabilities 4. Scans code for bad practices (duplicated logic, debts and code smells) 5. Scans code for bugs ### Request access Sign into [sonarcloud.io](https://sonarcloud.io) and register your Github project. ### Build configuration There are different ways to enable Sonar in your project, follow the [Getting Started guide](https://sonarcloud.io/sessions/new) to know more. You can configure a SonarCloud badge by adding the following syntax at the top of your README.md: ``` [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=%3A&metric=alert_status)](https://sonarcloud.io/dashboard?id=<group-id>%3A<artifact-id>) ``` From the [`Account > Security`](https://sonarcloud.io/account/security/) menu of SonarCloud dashboard, you'll be able to generate the token that needs to be passed as `SONAR_TOKEN` environment variable. --- ## Sonatype Lifecycle > *"A better way to SCA"* Sonatype's Licecycle is an Open Source Software Supply Chain management platform to help identify and manage the 3rd party libraries within applications. |Solution:|Sonatype Lifecycle| |-|-| |Website|https://www.sonatype.com/| |Documentation|https://help.sonatype.com/en/sonatype-lifecycle.html| |Focus| Software Composition Analysis (SCA)| |Coverage|Over 14 languages| |Scan Output|SBOMs, CVEs, Licenses, Remediation Guidance| Modern applications consist of over 85% open source software. The Sonatype Platform aims not only to identify which open source components are in use, but also identify their security and license risks, and determine the best path for remediation. All of this is powered by the largest proprietary CVE database and highest accuracy for identification in the market. *** Projects Onboarded to the [FINOS Sonatype Lifecycle Platform](https://finos.sonatype.app/): - [Morphir-Scala](https://github.com/finos/morphir-scala) - [Morphir-ELM](https://github.com/finos/morphir-elm) - [Morphir-JVM](https://github.com/finos/morphir-jvm) - [Morphir-Dotnet](https://github.com/finos/morphir-dotnet) ### Quickstart 1. Contact [help@finos.org](mailto:help@finos.org) to get onboarded onto the Sonatype platform. - Get user login. - Create organization and application. 2. Determine what kind of app you want to scan (https://help.sonatype.com/en/analysis.html). 3. Add the GitHub Actions plugin to your pipelines (https://help.sonatype.com/en/sonatype-github-actions.html). 4. Configure any other desired integrations (https://help.sonatype.com/en/sonatype-integrations.html). 5. Start evaluating results and remediating! ### A few best practices Details on the best way to scan your applications can be determined with the Sonatype team who can help guide your implementation. - Scan the application *after* build - Exclude driectories not deployed with the application: `-D dirExcludes="**/website/, **/docs/, **/.*" ` - Omit dev dependencies - Add the SBOM to the build output (https://help.sonatype.com/en/sonatype-github-actions.html#fetch-sbom-action) More best practices can be found here: https://help.sonatype.com/en/lifecycle-best-practices.html #### Scanning Mill / Coursier Projects When scanning an app being built by Mill and using Coursier as the cache, make sure to get the cache and copy it to a temporary directory so that the binary scan can identify the artifacts (the default configuration is to omit scanning the cache). ``` sonatype-scan: runs-on: ubuntu-latest steps: - name: Cache scala dependencies uses: coursier/cache-action@v6 - name: Get OUT cache uses: actions/cache/restore@v4 with: path: out/ key: ${{ runner.os }}-* - name: Copy Cache for SCA Scan run: | mkdir depCache/ #Create local copy of cache for Sonatype Scanner cp -r /home/runner/.cache/coursier/ depCache/ - name: Sonatype Lifecycle SCA Scan ... ``` #### Scanning Paket / .NET Projects When scanning Paket or .NET projects the CycloneDX dotnet plugin can help build out the dependency tree. Also the Windows CLI from the [Sonatype downloads page](https://help.sonatype.com/en/download-and-compatibility.html) can be used for scanning on Windows VMs (current official plugin only supports Linux VMs). Implementation example: ``` - name: Resolve Paket Dependencies run: | dotnet tool install --global Paket dotnet tool restore paket install .\build.cmd DotnetRestore - name: Create CycloneDX SBOM (transitive mapping) run: | dotnet tool install --global CycloneDX dotnet restore copy build/build.fsproj SonatypeSCA.csproj echo $env:SBOM_Path dotnet CycloneDX SonatypeSCA.csproj -o packages/ - name: Download and Scan with Sonatype Lifecycle CLI if: always() run: | curl --location https://sonatype-download.global.ssl.fastly.net/repository/downloads-prod-group/scanner/nexus-iq-cli-1.182.0-01+864-windows.zip > Sonatype.zip tar -xf Sonatype.zip rm Sonatype.zip .\nexus-iq-cli.exe -s ${{ env.SonatypeUrl }} -a ${{ secrets.SONATYPE_USER }}:${{ secrets.SONATYPE_PASSWORD }} -t ${{ env.SonatypeStage }} ${{ env.ExcludeDirectory }} -r sonatype-results.json -i ${{ env.SonatypeAppId }} ${{ env.SonatypeScanTarget }} - name: Upload Sonatype Scan Results if: always() uses: actions/upload-artifact@v4 with: name: ${{ env.SonatypeAppId }} Sonatype Scan Results path: sonatype-results.json ``` --- ## Whitesource | | | |--- | :---| | **Name** | Whitesource | | **Status** | Delivered | | **Link** | [whitesourcesoftware.com](https://whitesourcesoftware.com) | | **Topics** | Legal, Security, Quality | | **Languages** | Javascript | [WhiteSource](https://www.whitesourcesoftware.com/) automatically identifies all the open source components and dependencies in your build by constant and automatic cross-referencing of your open source components against WhiteSource’s definitive database of open source repositories. WhiteSource provides a dedicated instance to validate and enforce security and legal compliance for all Symphony Software Foundation hosted projects. Below are listed the main WhiteSource features that have been adopted by Foundation projects. 1. Check libraries for outdated versions 2. Check libraries for security vulnerabilities 3. Check libraries for bugs 4. Check libraries for problematic/undefined licenses 5. Check libraries for release activity 6. Integration with CI environments ### Glossary To avoid confusion, below are listed some WhiteSource concepts that differ with the definitions used within the Foundation. 1. A **FINOS repository** is a Github repository hosted by the Foundation; in WhiteSource terms, this is called a project 2. A **FINOS Project** is a logical entity that includes a. one or more project leaders b. a project team c. one or more Foundation repositories; if one, project and repository will have the same name. d. In WhiteSource terms, this is called a product and can be accessed directly by the WhiteSource main menu; each **WhiteSource Product** will list below the projects included. 3. **Foundation WhiteSoure dashboard** - WhiteSource provides a dedicated instance for the Foundation projects that can be accessed a. by all project leaders, to check and export project metrics b. by Foundation Staff, to configure Foundation WhiteSource policies 4. **Foundation WhiteSource policies** - A collection of rules and workflows implemented in the WhiteSource dashboard by the Foundation team to enforce security and legal compliance; below are reported the details. 5. **Alert** - The visual notification that WhiteSource shows in the main dashboard when a policy violation is found ### Features WhiteSource provides the following features to Foundation project leads/committers that have been granted access: 1. Access the WhiteSource dashboard for one or more projects a. Access WhiteSource Due Diligence and Risk reports b. Browse (and drill down) through project libraries c. Browse (and drill down) through licenses found in the project d. Check alerts and warnings triggered by policy violations 2. Configure WhiteSource build plugins to upload project metrics 3. Configure Travis CI (or other CI environments) to continuously a. validate code against Foundation policies enforced by WhiteSource b. fail the build, if any policy violation is found c. upload project metrics to the WhiteSource Foundation dashboard ### WhiteSource Policies Below are the WhiteSource policies that have been configured by the Foundation and are enforced across all integrated projects; all libraries that are scanned in a project are matched against the following policies, in the order reported below, until a policy is matched. 1. [SECURITY] Reject High Security Vulnerability Severity - any library that contains high level CVEs is marked as Rejected, 2. [SECURITY] Reject High Security Vulnerability Score - any library that contains CVEs with score higher than 7 is marked as Rejected, 3. [QUALITY] Reject High Bug Rating - any library [high bug rating](https://www.whitesourcesoftware.com/open-source-bug-tracking/) is marked as Rejected, 4. [LEGAL] Licenses that require review - any library with unknown license is marked as Rejected, 5. [QUALITY] Reassign Low Version Activity - any library with a low amount of versions released is Reassigned to the project lead for validation, 6. [QUALITY] Reassign Stale (5 years) Library - any library without a release for more than 5 years is Reassigned to the project lead for validation, 7. `[LEGAL] Reject Problematic (Category X license) libraries - any library using a Category X license, as indicated in our contribution legal requirements, are marked as Rejected.` Note that legal policies are currently disabled due to the large amount of false positive generated by dual-licensed libraries. We are working to improve things. ### Integration with GitHub.com FINOS have rolled out the [Mend (formerly WhiteSource) integration for GitHub.com](https://docs.mend.io/integrations/latest/understand-mend-for-github-com), which enables: 1. Automatic (and configurable) scanning of all commits on the default branch (commonly master) and Pull Requests 2. Automatic (and configurable) scanning of all Pull Requests against the default branch (commonly master) 3. Support for most of languages and build tools currently used in FINOS projects 4. Creation of GitHub issues with CVE description and meta; please find the issue details on the [Mend docs page](https://docs.mend.io/integrations/latest/viewing-mend-issues) #### FINOS default configurations There are 2 configuration files to define at repository level, in order to enable the WhiteSource integration with GitHub.com: .whitesource file configures the bot and whitesource.config configures the WhiteSource agent. ##### .whitesource Specifies whether to use GitHub Issues or not and points to the WhiteSource agent configuration. You can copy this file definition from https://github.com/finos/software-project-blueprint ``` .whitesource { "scanSettings": { "configMode": "LOCAL" }, "checkRunSettings": { "vulnerableCheckRunConclusionLevel": "failure" }, "issueSettings": { "minSeverityLevel": "LOW" } } ``` ##### whitesource.config Specifies build-time configurations, including language-specific settings, file inclusions/exclusions and more. You can copy the default configuration from [FINOS software project blueprint](https://github.com/finos/software-project-blueprint). More info can be found on the [Unified Agent configuration parameters](https://docs.mend.io/legacy-sca/latest/unified-agent-configuration-parameters) docs page. #### Enable WhiteSource scanning 1. Read the [Mend for GitHub.com integration](https://docs.mend.io/integrations/latest/understand-mend-for-github-com) documentation, to know what it does and how 2. Email [help@finos.org](mailto:help@finos.org) to request the activation of WhiteSource integration on a FINOS hosted project a. When enabled, the app will create a Pull Request to add a .whitesource file in the codebase root 3. Merge the Pull Request raised on point #2 #### Testing WhiteSource scanning :::caution This integration only scans for new CVEs that are introduced by a code change, therefore the build is triggered only when a build descriptor is updated, ie `pom.xml` or `package.json`. If you'd like to be notified about new and upcoming CVEs, please email help@finos.org and request email notification for new CVEs spotted on a given project. ::: The easiest and less invasive way to test is to create a new branch, add a dependency with security vulnerabilities and commit the change; few minutes later (time depends on build complexity), the app will have created one GitHub Issue for each CVE found. If no issues are created, and want to know if the scan was performed, email [help@finos.org](mailto:help@finos.org) and FINOS team will help you debugging bot's execution. #### Configuring WhiteSource scanning False positives are expected, when enabling the WhiteSource integration, because of a long list of factors related with the (sometimes low) quality of the downstream library that you're consuming; being able to fine-tune the WhiteSource agent is very important, in particular excluding files and folders that should not be scanned, which is necessary most of the times. To have the ability to exclude files and folders, please follow instructions on https://docs.mend.io/bundle/integrations/page/global_repo_configuration.html Please note that there may be additional configurations to apply, based on your build requirements and tools; build-specific configurations can be viewed on the [Unified Agent Package Manager Dependency Resolvers](https://docs.mend.io/legacy-sca/latest/unified-agent-configuration-parameters#package-manager-dependency-resolvers) docs, and see what applies to your project configuration. ### Build integration As alternative to the GitHub.com integration, WhiteSource also provides an agent (CLI tool) that can be downloaded and executed from any environment; this may be necessary in case the project's build tool or language are not supported by WhiteSource and some custom build logic must be performed to prepare for the scanning. Many build servers are supported, including Travis CI, the most used tool used by FINOS hosted projects Glossary To avoid confusion, below are listed some WhiteSource concepts that differ with the definitions used within the Foundation. A Foundation repository is a Github repository hosted by the Foundation; in WhiteSource terms, this is called a project A Foundation project is a logical entity that includes one or more project leaders a project team one or more Foundation repositories; if one, project and repository will have the same name. In WhiteSource terms, this is called a product and can be accessed directly by the WhiteSource main menu; each WhiteSource product will list below the projects included. Additionally, a convenience script has been created and saved to [https://github.com/finos/contrib-toolbox/blob/main/scripts/wss-maven-scan.sh](https://github.com/finos/contrib-toolbox/blob/main/scripts/wss-maven-scan.sh) which can be used for simplifying one-off scanning of projects; it requires a WhiteSource API key that must requested via [help@finos.org](mailto:help@finos.org), and accepts GitHub repo coordinates, a GitHub user/org name and a GitHub repository name. Below an example to submit metrics for the Open Developer Platform repo. ``` export WSS_API_KEY="xxx" curl -L https://raw.githubusercontent.com/finos/contrib-toolbox/master/scripts/wss-maven-scan.sh | bash -s -- finos software-project-blueprint ``` ### Request access You can request access to the FINOS WhiteSource dashboard if you're part of a FINOS project team; please send an email to [help@finos.org](mailto:help@finos.org) that specifies: 1. the email address you'd like to use to login 2. the Foundation project you would like to scan with WhiteSource --- ## Continuous Delivery Continuous Delivery (CD - read the [definition given by Martin Fowler](https://martinfowler.com/bliki/ContinuousDelivery.html)) allows project leads and committers to configure automated processes to build and deploy their software. FINOS provides a [dedicated OpenShift Online instance](#openshift-console) that can be used for this purpose. ### Openshift Console The Open Developer Platform provides access to a FINOS [OpenShift Container Platform](https://www.openshift.com/products/container-platform/) instance (also called FINOS OpenShift Console), the leading enterprise Kubernetes distribution, so that developers can try out integrations with other containers, build and test containerised architectures and enable continuously deployed code build pipelines. Access is granted (free of charge) to all FINOS project teams (see below); in this page we guide contributors to request access, understand the OpenShift FINOS setup and execute the first tests. ### How to get access In order to access the FINOS OpenShift Console, it is necessary to comply with the following requirements: 1. You must be part of a FINOS project team 2. You must have an account on developers.redhat.com; you can also sign up with your GitHub credentials To request access, send an email to [help@finos.org](mailto:help@finos.org), with the following info: 1. Name, surname and company 2. Corporate email address 3. GitHub ID 4. Red Hat Login ID (when logged into Red Hat Developers portal, go to the account page) 5. FINOS Project team you are part of The FINOS Infra team will create a project for your project, grant permissions to your Red Hat user and notify you via email the link to access the FINOS OpenShift Console. ### Travis CI to OpenShift integration Travis CI [configuration](https://docs.travis-ci.com/user/customizing-the-build/) can be extended trigger the OpenShift image build and deployment; to make configuration easier, the Foundation provides a script called [`oc-deploy.sh`](https://github.com/finos/contrib-toolbox/blob/main/scripts/oc-deploy.sh) that can be executed as `after_success` script and triggers a containerised deployment, using the OpenShift CLI tool; with a simple bash line, the following operations are performed: 1. Install OpenShift CLI (oc) in the current environment (see `OC_VERSION` and `OC_RELEASE`) 2. Logs into OpenShift Online (see `OC_ENDPOINT`) and select the right OpenShift project (see `OC_PROJECT`) 3. Deletes - if `OC_DELETE_LABEL` is defined - all OpenShift resources marked with the specified `key=value` label 4. Processes - if `OC_TEMPLATE` file exists and is valid - and creates all OpenShift resources defined within; template parameter values can be passed using the `OC_TEMPLATE_PROCESS_ARGS` configuration variable 5. Triggers the build of an OpenShift image, identified by the `BOT_NAME` configuration variable, uploading the application binary as ZIP archive (see `OC_BINARY_ARCHIVE`) or a folder (see `OC_BINARY_FOLDER`) that have been generated by the project build; the folder is preferred over the archive binary distribution, as it's less likely to cause network timeouts during the upload Below is the Travis configuration. ``` ... after_success: curl -s https://raw.githubusercontent.com/symphonyoss/contrib-toolbox/master/scripts/oc-deploy.sh | bash ``` ### Configuration The oc-deploy.sh script requires some mandatory environment variables to be defined before executing the script; the mandatory ones are: - `OC_TOKEN` - The Openshift Online token - `BOT_NAME` - the name of the BuildConfig registered in OpenShift, which is used to start the OpenShift build - `OC_TEMPLATE` - Path of an OpenShift template to (oc) process and create, if existent; defaults to .openshift-template.yaml - `OC_BINARY_ARCHIVE` or `OC_BINARY_FOLDER` - Relative path to the ZIP file (or folder) to upload to the container as source - Any other environment variable containing template parameters, see `OC_TEMPLATE_PROCESS_ARGS` below Please review the default values of the following variables: - `OC_DELETE_LABEL` - Used to delete a group of resources with the same label; If set, the script will invoke `oc delete all -l <OC_DELETE_LABEL>`; example: `OC_DELETE_LABEL="app=mybot"` - `OC_TEMPLATE_PROCESS_ARGS` - Comma-separated list of environment variables to pass to the OC template; defaults to null; example `OC_TEMPLATE_PROCESS_ARGS="BOT_NAME,S2I_IMAGE"` - `OC_VERSION` - OpenShift CLI version; defaults to `1.5.1` - `OC_RELEASE` - OpenShift CLI release; defaults to `7b451fc-linux-64bit` - `OC_ENDPOINT` - OpenShift server endpoint; defaults to `https://api.starter-us-east-1.openshift.com` - `OC_PROJECT_NAME` - The Openshift Online project to use; default is `ssf-dev`, no changes needed - `OC_ENDPOINT` - OpenShift server endpoint; defaults to `https://api.pro-us-east-1.openshift.com` , no changes needed - `SKIP_OC_INSTALL` - Skips the OpenShift CLI (oc) installation; defaults to false; useful for local `oc-deploy.sh` test runs The example below shows a pseudo CI configuration. ``` env: global: - BOT_NAME="mybot" - OC_DELETE_LABEL="app=mybot" - SYMPHONY_POD_HOST="foundation-dev.symphony.com" - SYMPHONY_API_HOST="foundation-dev-api.symphony.com" - OC_BINARY_FOLDER="vote-bot-service/target/oc" - OC_TEMPLATE_PROCESS_ARGS="BOT_NAME,SYMPHONY_POD_HOST,SYMPHONY_API_HOST" after_success: curl -s https://raw.githubusercontent.com/symphonyoss/contrib-toolbox/master/scripts/oc-deploy.sh | bash ``` #### Project setup In order to configure Continuous Delivery, the project must meet few requirements and some configuration must be defined. 1. **Memory (size) and CPU (number) requirements must be known** upfront 2. The [**deployment strategy**](https://docs.redhat.com/en/documentation/openshift_container_platform/3.3/html/developer_guide/deployments#dev-guide-deployment-strategies) **must be known** upfront; default is RollingDeployment, which spins up a new container in parallel to the existing one, switches traffic when the new one is ready and finally kills the existing one. 3. Collect all passwords and secrets that are needed by the applications to run; the Foundation Staff will register these entries as secrets in OpenShift and deliver secret key references 4. The build process MUST generate a folder that: a. **MUST contain all the artifacts** to run the application; for Maven builds, the assembly plugin can be used b. **MUST contain a (Unix) run script**; for Maven builds, the [appassember plugin](https://www.mojohaus.org/appassembler/appassembler-maven-plugin/) can generate it c. **MUST NOT contain any password**, secret or sensitive data (like emails, names, addresses, etc) in clear text; [OpenShift secrets](https://docs.redhat.com/en/documentation/openshift_container_platform/4.6/html/nodes/working-with-pods#nodes-pods-secrets) provide a safe way to manage them 5. Follow the instructions below to define an [OpenShift template](https://docs.redhat.com/en/documentation/openshift_container_platform/4.9/html/images/using-templates) called `.openshift-template.yaml`, in the root folder of the GitHub repository ### Template definition Below is described, section by section, an OpenShift template that defines 1. The Docker image build process for the given app 2. The image stream that triggers a deployment configuration when an image is created 3. The deployment configuration that defines - among other things - the containers to run and its configuration You will notice that all resources configured below define an app label with the same value, which allows to run commandline commands across all resources with the same label, for example `oc delete all -l app=mybot` #### Template name and parameters This is the header of the file, which defines the template name mybot-template and a list of parameters, like BOT_NAME; parameters must be exported as environment variables before invoking `oc-deploy.sh` (see above); from the objects: line below, the Openshift configuration resources are defined. ``` apiVersion: v1 kind: Template metadata: name: mybot-template parameters: - name: BOT_NAME description: The Bot name displayName: Bot Name required: true value: "mybot" - name: SEND_EMAIL description: Whether the bot should send emails or not; defaults to true displayName: Send Email? required: true value: "true" ... objects: ``` #### Images and streams The OpenShift image creation process is carried by a container called deployer and described by the BuildConfig resource, which takes as parameters: - a `sourceStrategy`, which identifies the container image used to build the deployer container and points to the `ImageStream` with name `s2i-java` - the output image name and tag, which points to the `ImageStream` with name matching the BOT_NAME variable See the example below. ``` - apiVersion: v1 kind: ImageStream metadata: labels: app: ${BOT_NAME} name: s2i-java spec: dockerImageRepository: "docker.io/jorgemoralespou/s2i-java" - apiVersion: v1 kind: ImageStream metadata: labels: app: ${BOT_NAME} name: ${BOT_NAME} spec: {} status: dockerImageRepository: "" - apiVersion: v1 kind: BuildConfig metadata: name: ${BOT_NAME} labels: app: ${BOT_NAME} spec: output: to: kind: ImageStreamTag name: ${BOT_NAME}:latest postCommit: {} resources: {} runPolicy: Serial source: type: Binary binary: strategy: type: Source sourceStrategy: from: kind: ImageStreamTag name: s2i-java:latest triggers: {} ``` #### Deployment configuration The DeploymentConfig resource defines: 1. The deployment strategy, defaults to `Rolling` 2. The container configuration a. The image to use to create the container; this must match with the ImageStream output defined above b. TCP/UDP ports to expose; in this case port `8080` is open at container level c. The [`readinessProbe`](https://docs.redhat.com/en/documentation/openshift_container_platform/4.6/html/applications/application-health) detects if the container is unhealthy d. Container environment variables can be defined in clear text (ie `LOG4J_FILE`) or loaded from a secret key reference; secrects are managed by the Foundation Staff and are normally used to manage credentials used to access the external APIs. 3. The deployment configuration `trigger`, pointing to the `latest` tag of an image named after the BOT_NAME variable See the example below. ``` - apiVersion: v1 kind: DeploymentConfig metadata: labels: app: ${BOT_NAME} name: ${BOT_NAME} spec: replicas: 1 selector: app: ${BOT_NAME} deploymentconfig: ${BOT_NAME} strategy: rollingParams: intervalSeconds: 1 maxSurge: 25% maxUnavailable: 25% timeoutSeconds: 600 updatePeriodSeconds: 1 type: Rolling template: metadata: labels: app: ${BOT_NAME} deploymentconfig: ${BOT_NAME} spec: containers: - image: ${BOT_NAME}:latest imagePullPolicy: Always name: ${BOT_NAME} ports: - containerPort: 8080 protocol: TCP readinessProbe: httpGet: path: "/healthcheck" port: 8080 initialDelaySeconds: 15 timeoutSeconds: 1 env: - name: LOG4J_FILE value: "/opt/openshift/log4j.properties" - name: TRUSTSTORE_PASSWORD valueFrom: secretKeyRef: name: ${BOT_NAME}.certs key: truststore.password ... ... ... triggers: - type: ConfigChange - imageChangeParams: automatic: true containerNames: - ${BOT_NAME} from: kind: ImageStreamTag name: ${BOT_NAME}:latest type: ImageChange status: {} ``` #### Service definition In order to access the container port, it is necessary to define 1. a Service that acts as load-balancer across all containers with an `app` label matching the BOT_NAME variable 2. a Route that registers to the OpenShift DNS and points to the Service See the example below. ``` - apiVersion: v1 kind: Service metadata: annotations: openshift.io/generated-by: OpenShiftNewApp labels: app: ${BOT_NAME} name: ${BOT_NAME} spec: ports: - name: healthcheck-tcp port: 8080 protocol: TCP targetPort: 8080 selector: app: ${BOT_NAME} deploymentconfig: ${BOT_NAME} sessionAffinity: None type: ClusterIP status: loadBalancer: {} - apiVersion: v1 kind: Route metadata: name: ${BOT_NAME} labels: app: ${BOT_NAME} spec: to: kind: Service name: ${BOT_NAME} weight: 100 port: targetPort: healthcheck-tcp wildcardPolicy: None ``` ### Useful commands Below are some commands we found useful while setting up our Symphony bots on OpenShift Online, using the [OpenShift CLI (`oc`)](https://docs.redhat.com/en/documentation/openshift_container_platform/3.9/html/cli_reference/cli-reference-get-started-cli). ``` # Login on FINOS OpenShift - copy from https://console.pro-us-east-1.openshift.com/console/command-line export OC_TOKEN=... oc login https://api.pro-us-east-1.openshift.com --token=$OC_TOKEN # List of projects oc projects # Select a specific project; all next commands will refer to that project oc project my_bot # Show list of services, builds, pods and deployments for the current project oc status # Import an image from Docker Hub oc import-image maoo/s2i-java-binary --all --confirm # Processes an OpenShift template definition and passes parameter values oc process -f bot_template.yaml -p BOT_NAME=my_botname | oc create -f - # Start an OpenShift build, passing an archive or a folder oc start-build my_botname --from-archive=./target/archive.zip --wait=true oc start-build my_botname --from-dir=./target/my_botname --wait=true # Deletes all resources with label 'app' equals to 'my_botname' oc delete all -l app=my_botname ``` --- ## Clojure [**Clojure**](https://clojure.org/) is a dialect of the Lisp programming language that runs on the Java virtual machine, Common Language Runtime, and JavaScript engines; the Foundation hosts [some Clojure projects](https://github.com/finos?q=&type=&language=clojure) that can be browsed as examples. Clojure code can be built and distributed using different build tools, but [Leiningen](https://leiningen.org/) is the only most commonly used at FINOS. The deployable unit for Leiningen projects is a JAR file and matching POM, which means that Clojure projects can be deployed to any Maven repository. Wherever appropriate, the Foundation recommends following the [deployment rules for Java](java) (artifact naming and versioning, in particular). ### Badges Badges can be added at the top of the project's root-level `README.md` file, using the following Markdown syntax: ``` [![Clojars Project](https://img.shields.io/clojars/v//.svg)](https://clojars.org//) ``` ``` [![Maven Central](https://img.shields.io/maven-central/v//.svg?maxAge=2592000)](https://search.maven.org/#artifactdetails%7C%7C%7C2%7Cpom) ``` --- ## C# [**C#**](https://docs.microsoft.com/en-us/dotnet/csharp/) is an object-oriented language that runs on the .NET Framework; feel free to browse the [Foundation hosted projects written in C#](https://github.com/finos?q=&type=&language=c%23). ### Build The easiest way to locally build a C# project is to [use Visual Studio](https://msdn.microsoft.com/en-us/library/5tdasz7h.aspx), although it's also possible to use the [MSBuild](https://msdn.microsoft.com/en-us/library/dd393574.aspx) command-line tool; you can find more info on [Microsoft Developer Network](https://msdn.microsoft.com/en-us/library/cyz1h6zd.aspx). There is an open source, cross-platform alternative to the .NET Framework implementation called [Mono](https://www.mono-project.com/), based on the [ECMA](https://www.mono-project.com/docs/about-mono/languages/ecma/) standards for C# and the [Common Language Runtime](https://www.mono-project.com/docs/advanced/runtime/), however not all .NET applications can run on this platform, therefore it's safer to run all builds on a Windows environment that is configured with the .NET Framework installed. ### Release on NuGet [NuGet](https://nuget.org/) is the package manager for the Microsoft development platform including .NET. The [NuGet client tools](https://docs.nuget.org/ndocs/guides/install-nuget) provide the ability to produce and consume packages. The NuGet Gallery is the central package repository used by all package authors and consumers. To release a project on NuGet, it is currently required to run the build process from a .NET (Windows) environment, as there are some known issues for NuGet to run with Mono on Linux and OSX; please refer to [Mono issues](https://github.com/NuGet/Home/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+mono) on GitHub for more info. From command-line, you can invoke the following command: ``` nuget pack project.csproj -IncludeReferencedProjects -Prop Configuration=Release ``` A badge can be added at the top of the project's root-level README.md file, using the following Markdown syntax: ``` [![NuGet Packages Status](https://img.shields.io/nuget/v/.svg?maxAge=2592000)](https://www.nuget.org/packages//) ``` You can also run this process continuously on each commit and publish pre-releases by integrating with MyGet. --- ## Docker Build and Publish ### Why Docker? Many organizations require obtaining and deploying software packages from an image for ease of deployment. Furthermore, there can be strict requirements for those images to be signed or provide provenance attestations, as well as come from a trusted source such as Docker Hub or GitHub Container Registry. [Publishing to Docker Hub](https://hub.docker.com/r/finos/) and verifying provenance allows FINOS projects to increase adoption by making deployments easy, consistent and trusted - something especially important for enterprise users. ### Getting started In order to start publishing your image to Docker Hub, you'll first need to create a `Dockerfile` to define what the runtime environment should look like, install dependencies and build the project. Then, you'll need a GitHub workflow `.github/workflows/docker-publish.yml` to check out the repository, and then build and publish the Docker image. Optionally, a `docker-compose.yml` can be created for ease of local development and testing. This is not needed when publishing to Docker Hub, which only requires a Dockerfile. #### `Dockerfile` Your Dockerfile will vary wildly depending on which dependencies you need to build the project, your project's runtime environment(s), etc. A guide on [how to write a basic Dockerfile](https://docs.docker.com/get-started/docker-concepts/building-images/writing-a-dockerfile/) is available in the Docker documentation. Even if there isn't a one-size-fits-all solution, there are general best practices that are good to follow when writing a Dockerfile. Here's a [sample Dockerfile from GitProxy](https://github.com/finos/git-proxy/blob/main/Dockerfile): ```Dockerfile FROM node:24@sha256:5a593d74b632d1c6f816457477b6819760e13624455d587eef0fa418c8d0777b AS builder USER root WORKDIR /out COPY package*.json ./ COPY tsconfig.json tsconfig.publish.json proxy.config.json config.schema.json test-e2e.proxy.config.json vite.config.ts index.html index.ts ./ RUN npm pkg delete scripts.prepare && npm ci --include=dev COPY src/ /out/src/ COPY public/ /out/public/ RUN npm run build-ui \ && npx tsc --project tsconfig.publish.json \ && cp config.schema.json dist/ \ && npm prune --omit=dev FROM node:24@sha256:5a593d74b632d1c6f816457477b6819760e13624455d587eef0fa418c8d0777b AS production COPY --from=builder /out/package*.json ./ COPY --from=builder /out/node_modules/ /app/node_modules/ COPY --from=builder /out/dist/ /app/dist/ COPY --from=builder /out/build /app/dist/build/ COPY proxy.config.json config.schema.json ./ COPY docker-entrypoint.sh /docker-entrypoint.sh USER root RUN apt-get update && apt-get install -y \ git tini \ && rm -rf /var/lib/apt/lists/* RUN mkdir -p /app/.data /app/.tmp /app/.remote \ && chown -R 1000:1000 /app USER 1000 WORKDIR /app EXPOSE 8080 8000 ENTRYPOINT ["tini", "--", "/docker-entrypoint.sh"] CMD ["node", "--enable-source-maps", "dist/index.js"] ``` This file is specific to GitProxy, but it showcases elements that are good to have in any `Dockerfile`: - **Multi-stage builds**: We divide the work into a `builder` stage that compiles/installs everything, and a `production` stage that copies over the final artifacts. This keeps image sizes small and prevents shipping dev tooling into production - **Pinning images to SHA digests**: Notice that image versions include a SHA. This is needed because tags are mutable. Pinning to a specific SHA guarantees the environment is properly replicated - **Running as non-root**: Setting `USER 1000` allows minimizing privileges before initializing the app - **Tini entrypoint**: Sets the entrypoint to Tini, which allows reaping zombie processes and forwarding signals from Docker to the app #### `docker-publish.yml` This file should be created in your `.github/workflows` directory to automate the build and publish process. In this file, we can detail *when* and *how* we want to publish to Docker Hub, for example: - Publish a `my-project:main` tag every time something gets pushed to `main` - Publish a `my-project:latest` tag whenever a new version of our software is published - Publish a `my-project:X.Y` tag when publishing a specific version of our software Here's an example of a [`docker-publish.yml` workflow from GitProxy](https://github.com/finos/git-proxy/blob/main/.github/workflows/docker-publish.yml): ```yml name: Build and Publish Docker Image on: push: branches: [main] release: types: [published] jobs: docker-build-publish: name: Build and Publish Docker Image runs-on: ubuntu-latest steps: - name: Set up Docker Buildx uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4 - name: Checkout Repository uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 - name: Log in to Docker Hub if: github.repository_owner == 'finos' uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4 with: username: finos password: ${{ secrets.DOCKER_PASSWORD }} - name: Set Docker Image Tag id: tags run: | if [ "${{ github.event_name }}" = "release" ]; then echo "tags=${{ github.repository }}:${{ github.ref_name }},${{ github.repository }}:latest" >> $GITHUB_OUTPUT else echo "tags=${{ github.repository }}:main" >> $GITHUB_OUTPUT fi - name: Build and Publish Docker Image if: github.repository_owner == 'finos' uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7 with: context: . file: Dockerfile push: true tags: ${{ steps.tags.outputs.tags }} provenance: true ``` You can tweak when to run the workflow as follows: ```yml on: push: branches: [main] # Run when pushing to main release: types: [published] # Run when publishing a release (via GitHub) ``` Note that the following section requires a `DOCKER_PASSWORD` repository secret to log into the `finos` Docker Hub account. Please contact [help@finos.org](mailto:help@finos.org) to set it up: ```yml - name: Log in to Docker Hub if: github.repository_owner == 'finos' # Only allow workflow to run from upstream repository uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4 with: username: finos password: ${{ secrets.DOCKER_PASSWORD }} ``` The following bit tags the image depending on whether the workflow got triggered on release or a regular push. Then, it automatically sets the tag name to the repository name and appends `:latest`, `:main` or `:X.Y` depending on what triggered the flow: ```yml - name: Set Docker Image Tag id: tags run: | if [ "${{ github.event_name }}" = "release" ]; then echo "tags=${{ github.repository }}:${{ github.ref_name }},${{ github.repository }}:latest" >> $GITHUB_OUTPUT else echo "tags=${{ github.repository }}:main" >> $GITHUB_OUTPUT fi ``` Finally, the image gets published to Docker Hub using the tags determined earlier. The `provenance: true` flag includes a [provenance attestation](https://docs.docker.com/build/metadata/attestations/slsa-provenance/), often used for security and auditing purposes: ```yml - name: Build and Publish Docker Image if: github.repository_owner == 'finos' uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7 with: context: . file: Dockerfile push: true tags: ${{ steps.tags.outputs.tags }} provenance: true ``` #### docker-compose.yml A `docker-compose.yml` can be optionally used for using images locally and testing. This isn't required for deploying to Docker Hub. Here's an [example `docker-compose.yml` from GitProxy](https://github.com/finos/git-proxy/blob/main/test/e2e/docker-compose.yml) for reference. ### Verification If everything is working as expected, you should find your published image in the [Docker Hub FINOS profile](https://hub.docker.com/r/finos/) after successfully running the `docker-publish.yml` workflow. If it doesn't show up, there was likely an error in the workflow itself, or during the `Dockerfile` build process. For more details on why the flow failed, check out the **Actions** tab on your repository and look for the **Build and Publish Docker Image** action to see the workflow execution output along with the reason for failure. You may also want to verify that the `Dockerfile` build works locally before running it in your project's CI pipeline. --- ## Continuous Integration Continuous Integration (CI) runs validation automatically at commit and merge time, helping teams detect problems earlier. CI setup is language- and ecosystem-specific (see `Release and deployment` below). The Open Developer Platform helps FINOS projects adopt CI tools and services, including options provided by vendors that support the FINOS community, like WhiteSource, GitHub and RedHat. The sections below cover CI engines used across FINOS projects. While many projects historically used Travis CI, most have moved toward GitHub Actions since [its release in 2019](https://github.blog/2019-08-08-github-actions-now-supports-ci-cd/). ### GitHub Actions GitHub gives the ability to create, reuse and share actions, which can be easily described as workloads that can be triggered on a wide range of events. Actions can be only defined at repository level, creating a `YAML` file in the `.github/workflows` folder. The `Actions` tab available in `github.com` web UI will list the actions defined and show the execution logs. The Open Developer Platform uses GitHub Actions for the following use cases: - Building and publishing Project websites To learn how to use GitHub Actions, start reading [https://help.github.com/en/actions](https://help.github.com/en/actions). When it's time to start writing your first `.yml` file, we found extremely helpful the following resources: - [Using the GITHUB_TOKEN in a workflow](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#using-the-github_token-in-a-workflow) - [Context and expression syntax](https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions) - [Event Types & Payloads](https://developer.github.com/v3/activity/events/types/) #### Example of Configuring Integration Testing In order to run this sample (some Symphony sample bots), the Travis build needs to be configured to add the following items: ``` # Download certificate before the build script runs before_script: "curl -s https://raw.githubusercontent.com/symphonyoss/contrib-toolbox/master/scripts/download-files.sh | bash" ``` ``` # Define environment variables with Symphony Pod endpoints env: global: - FOUNDATION_API_URL=https://foundation-dev-api.symphony.com - FOUNDATION_POD_URL=https://foundation-dev.symphony.com - SESSIONAUTH_URL=$FOUNDATION_API_URL/sessionauth - KEYAUTH_URL=$FOUNDATION_API_URL/keyauth - POD_URL=$FOUNDATION_POD_URL/pod - AGENT_URL=$FOUNDATION_POD_URL/agent ``` At this point, the certificates are in place and downloaded into the build box; integration tests can resolve User Identity certificates by accessing environment variables. The [symphony-java-sample-bots](https://github.com/symphonyoss/symphony-java-sample-bots/) was amongst the first Foundation projects that was enabled to run integration tests from Travis CI; the [Travis build logs](https://travis-ci.org/symphonyoss/symphony-java-sample-bots/) for this project show the info below. - The (hidden) environment variables that identify User Identity certificates (in this case 2, one for the message sender, one for the message receiver) ``` # Setting environment variables from repository settings $ export DOWNLOAD_PATH=[secure] $ export DOWNLOAD_ITEMS=[secure] $ export TRUSTSTORE_FILE=[secure] $ export TRUSTSTORE_PASSWORD=[secure] $ export BOT_USER_EMAIL=[secure] $ export BOT_USER_CERT_FILE=[secure] $ export SENDER_USER_EMAIL=[secure] $ export SENDER_USER_CERT_FILE=[secure] $ export DOWNLOAD_HOST=[secure] $ export SENDER_USER_CERT_PASSWORD=[secure] $ export BOT_USER_CERT_PASSWORD=[secure] ``` - The integration test logs of a successful run ``` ------------------------------------------------------- T E S T S ------------------------------------------------------- Running org.symphonyoss.simplebot.EchoBotIT chat initialised Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.132 sec - in org.symphonyoss.simplebot.EchoBotIT Results : Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 ``` ##### Known Certificate Issues ``` Caused by: javax.crypto.BadPaddingException: Given final block not properly padded at org.symphonyoss.simplebot.EchoBotIT.sendAndReceiveEcho(EchoBotIT.java:64) ``` This basically means that the certificate password is wrong; to validate the certificate using the following command: ``` openssl pkcs12 -info -nodes \ -in \ -passin pass: ``` Reminder for Foundation staff: every password symbol must be escaped by prefixing it with character ‘\’, before setting it as Travis environment variable. ##### Branch specific build commands Travis CI does not provide a syntax to specify branch-specific build commands; however, it is possible to use the following bash syntax (applicable to most CI environments) to workaround it; in this example, the Maven build will use the `sonar` profile only if the current branch is master. ``` script: - "[[ $TRAVIS_BRANCH =~ master ]] && mvn clean deploy -Pintegration-testing,sonar --settings settings.xml" - "[[ $TRAVIS_BRANCH =~ dev ]] && mvn clean deploy -Pintegration-testing --settings settings.xml" ``` ### Azure Pipelines FINOS can provide projects with Azure Pipelines integration on [https://dev.azure.com/finosfoundation](https://dev.azure.com/finosfoundation). You can follow docs on the [Microsoft docs page](https://docs.microsoft.com/en-us/azure/devops/pipelines/create-first-pipeline) ### MyGet [Myget](https://myget.org/) is a friction-free continuous integration & delivery for your nuget, npm, bower and vsix packages; the Foundation provides package repositories, which allow: 1. **Pre-release build and publishing**, using build environments that are equipped with .NET Framework and Visual Studio (headless); it also features source code tagging and version updates on source code based on incremental build number, to fully automate the package publishing pipeline 2. **Sync with NuGet**, that can be either manual (promoting pre-releases to releases using MyGet web interface) or automatic (a committer must create a personal account on MyGet and request access from the Foundation in order to be able to push packages) In order to request a project to be integrated with MyGet, a Project lead can sign up to MyGet and email [help@finos.org](mailto:help@finos.org) the following info: 1. Project coordinates - GitHub project url and other useful info 2. MyGet username 3. CSProj and CS files - Where project descriptors are located 4. Packages - A list of the packages that need to be published; by default all packages are taken into account 5. Publishing strategy to NuGet - Whether to enable automatic publishing based on source code branching or rely on manual package pushing using the MyGet interface; if the latter, a MyGet personal account username must be provided An example of project building with MyGet is the Symphony [RestApiClient project](https://github.com/symphonyoss/RestApiClient), which is also published on the [FINOS MyGet repository](https://www.myget.org/feed/ssf-restapiclient/package/nuget/SymphonyOSS.RestApiClient) and [NuGet](https://www.nuget.org/packages/SymphonyOSS.RestApiClient/). Badges can be added at the top of the project's root-level `README.md` file, using the following Markdown syntax: - Build status: ``` [![MyGet Build Status](https://www.myget.org/BuildSource/Badge/?identifier=)](https://www.myget.org/feed//package/nuget/) ``` - Latest Pre-Release package published: ``` [![MyGet Pre Release](https://img.shields.io/myget//v/.svg)](https://www.myget.org/feed//package/nuget/) ``` ### Release and deployment #### Continuous (artifact) deployment in Java When using Java, Travis CI can be easily configured to publish new snapshot artifacts on commit; to enable this feature, a project committer can follow these simple steps: 1. Follow the Java Snapshot deployment configuration ; as a result, you should have username/password credentials (mentioned below as `CI_DEPLOY_USERNAME` and `CI_DEPLOY_PASSWORD`) to access issues.sonatype.org 2. Email [help@finos.org](mailto:help@finos.org) to request permission to deploy artifacts on Maven remote repositories; this action is not required if the developer has already been granted access previously 3. Commit a `settings.xml` file in the project root folder 4. Define `CI_DEPLOY_USERNAME` and `CI_DEPLOY_PASSWORD` variables with Travis CI; make sure that they're encrypted and hidden during the build process; the credentials to use are the ones defined on step 1; if you don't want to share your username/password credentials, you can request and use Nexus tokens 5. Change the `mvn` build command to a. Invoke the `deploy` goal b. Append `--settings settings.xml` at the end of the build command [This tutorial](https://coderwall.com/p/9b_lfq/deploying-maven-artifacts-from-travis) walks through the mentioned steps, with more details and configuration options. ##### settings.xml sample ``` ossrh ${env.CI_DEPLOY_USERNAME} ${env.CI_DEPLOY_PASSWORD} ``` #### Continuous release in Python Travis CI can be configured to use [python-semantic-release](https://python-semantic-release.readthedocs.io/en/latest/), a package that simplifies and automates versioning for python projects; a project lead can email [help@finos.org](mailto:help@finos.org) to request Foundation staff to apply the proper Travis CI project settings; packages will be published on behalf of the FINOS pypi user. #### Continuous release in NodeJS Travis CI can easily publish packages to npm using [semantic-release](https://github.com/semantic-release), which delegates release operations to your CI environment and allows you to control versioning [using commits (commitizen)](https://www.npmjs.com/package/commitizen); as a result, npm packages will be continuously released on each code repository change. [Follow our instructions](javascript) on how to register a package and user in the Foundation npm organisation. --- ## Java FINOS provides support for [Java projects](https://github.com/finos?q=&type=&language=java) by delivering: 1. The [FINOS Parent POM](https://github.com/finos/finos-parent-pom), a Maven POM Module that delivers out-of-the-box features for your FINOS-hosted Java project and saves some Maven configuration hassle 2. The provisioning, configuration and management of the [Maven Central Portal](https://central.sonatype.com) account required to publish your Java project into Maven Central. The FINOS Parent POM provides: 1. Plugin configuration for Java sources, Javadocs, Maven Site Plugin, Sonar and Docker 2. Release deployment in Maven Central using the Maven Release Plugin 3. Rules to validate Central Repository code requirements 4. Other integrations for checks and validations You can also use the FINOS Parent POM as inspiration to enhance your own (parent) POM, or choose other JVM-based build tools, such as [Gradle](https://gradle.org/), [Ant](https://ant.apache.org/), [Leiningen](https://leiningen.org/) or others, and inherit/replicate the FINOS Parent POM. ### Artifact publishing All Java projects hosted by the Foundation are expected to use `org.finos.` as `groupId`, in order to identify the source of the artifact, and associate it unequivocally to the FINOS project; all released artifacts for incubating and graduated projects must be hosted on [Maven central](https://central.sonatype.com/search?q=org.finos&smo=true). To publish artifacts into Maven Central, you can either use the FINOS Parent POM and inherit its configuration, or copy it [from here](https://github.com/finos/finos-parent-pom/blob/finos-7/pom.xml). We also strongly suggest to rely on CI/CD actions to execute the deployment, in order to avoid falling into OS or environment-specific challenges; the [FINOS Parent POM GitHub Action](https://github.com/finos/finos-parent-pom/blob/finos-7/.github/workflows/build.yml) provides a perfect example, which needs very little changes to adapt to any Maven project. First step is to make sure that the following tags are NOT included in your `pom.xml` files: 1. `` 2. `oss.sonatype.org` or `s01.oss.sonatype.org` 3. `maven-deploy-plugin` Also make sure that: 1. your GitHub Action generates GPG-signed (use self-signed certificates) artifacts, ready to be deployed 2. you have properly configured your versioning updates (either using the `maven-release-plugin` or manually, using the `maven-versions-plugin`) 3. your GitHub Action includes `configure-java`, using the following `server-*` and `gpg-*` parameters [shown here](https://github.com/finos/finos-parent-pom/blob/finos-7/.github/workflows/build.yml#L38) 4. the `server-id` on step d must match with the `` configuration of the `central-publishing-maven-plugin` in `pom.xml`; if you're using the FINOS Parent POM, you can override it using the `` property (default is `ossrh`) At this point you can request the setup of Maven Central credentials and GPG key for artifact signing to help@finos.org for your (FINOS) Github repository (the provisioning process normally takes 3-4 working days) and trigger the workflow. If auto publish is enabled (the default configuration for FINOS Parent POM) in the `central-publishing-maven-plugin`, you should be able to see your new artifact deployed on search.maven.org after roughly 30 minutes, without the need for any further action; otherwise, you'll need to access [central.sonatype.com](https://central.sonatype.com) with the project's email and password (needs to be requested to help@finos.org) and trigger the publishing (or drop) of the deployment(s). #### Maven Central Badge A badge can be added at the top of the project's root-level [README.md] file, using the following Markdown syntax: ``` [![Maven Central](https://img.shields.io/maven-central/v/org.finos/.svg?maxAge=2592000)](https://search.maven.org/#artifactdetails%7Corg.finos%7C%7C2%7Cpom) ``` ### Release The Maven Release Plugin, configured as part of the FINOS Parent POM, delivers the following features: 1. Verify that there are no uncommitted changes in the local workspace. 2. Prompt the user for the desired tag, release and development version names. 3. Modify and commit release information into the pom.xml file. 4. Tag the entire project source tree with the new tag name. 5. Extract file revisions versioned under the new tag name. 6. Deploy the versioned artifacts to appropriate local and remote repositories. You can manually run the release process using the following commands: ``` export GPG_TTY=$(tty) mvn release:prepare release:perform -Prelease ``` Note that the artifact publishing process is delivered by the `central-publishing-maven-plugin:plugin` goal, which is included in the `` property, see https://github.com/finos/finos-parent-pom/blob/finos-7/pom.xml#L75 #### Known issues If the release command fails with "gpg: signing failed: Inappropriate ioctl for device", run the following command and try again (see also the [GnuPG agent documentation](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html)). ``` export GPG_TTY=$(tty) ``` You can also override the `gpg` executable by adding `-Dgpg.executable=gpg2` in your CLI or into Maven profiles. ### Project Documentation Maven allows to generate a documentation website in HTML format and provides different options to publish such content on remote servers; content is composed by: 1. [Javadocs](https://www.oracle.com/java/technologies/javase/javadoc-tool.html) - can be easily generated using the [maven-javadoc-plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/), which is already configured to run during the build by the FINOS Parent Pom; the documentation is delivered in HTML format and included in the target/site/apidocs project sub-folder; to invoke the javadoc generation manually, you can invoke `mvn javadoc:javadoc`. 2. [Reporting](https://maven.apache.org/plugins/maven-site-plugin/examples/configuring-reports.html) - to collect different metrics from Maven build plugins and publish them as part of the docs. 3. [Free content](https://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html) - A free structure of documentation content, which supports different template languages (apt, fml, markdown, xdoc and xhtml) The FINOS Parent POM provides a configuration that allows to publish such content under the [FINOS Project Landscape](https://landscape.finos.org); to enable it, the build must be invoked using the `-Ppublish-site` Maven profile. For more info, follow the [related Pom documentation](https://github.com/finos/finos-parent-pom#github-plugins-configuration). --- ## Javascript In the last decade, Javascript (JS) has been increasingly used for backend software development, especially since the first appearance of Node.js. Listed below are some of the most common processes that are involved in a Javascript project lifecycle in several JS ecosystems/platforms, and how they interact with the project infrastructure provided by the Foundation. ### Node.js Node.js is a Javascript runtime for running JS code; the `node` command line is [easy to install](https://nodejs.org/en/download/) and provides a rich [set of options](https://nodejs.org/api/cli.html) to manage the entire project lifecycle. ### Publishing on npm [npm](https://docs.npmjs.com/) is the Node.js package manager, enabling developers to fetch and publish Node.js packages; project teams can use their own npm credentials to publish packages (locally or via CI), or ask [help@finos.org](mailto:help@finos.org) to support setting up the release process. To date, the Foundation has provisioned: 1. A FINOS NPMJS Organisation, that is used as a directory of all NPM packages that are released from a FINOS hosted project or working group. 2. A FINOS Admin user, which can be used to publish NPM packages to NPMJS, if a Project Lead is unable to create a personal account to do so 3. A Symphony Software Foundation NPMJS Organisation, that houses all published Node.js packages. #### Using package scoping All npm packages released under the FINOS npm organisation should define the @finos scope, in order to point to the npm organisation; if you're not familiar, [read more about scoped packages](https://docs.npmjs.com/misc/scope). There are some situations where it is not possible to specify the scope of a package, since scoping maybe used for behaviour-related aspects of the application; for example when [defining typescript typings](https://www.npmjs.com/org/types). ### Semantic release [Semantic release](https://semantic-release.gitbook.io/semantic-release/) is a Node.js library that automates the software release process by parsing commit messages; on every commit, semantic release is executed by Travis CI and - based on the commit message - decides to trigger a release or not; release managers can use [commitizen](https://commitizen.github.io/cz-cli/) (see image below) to simplify their commit process; simply type `npm install -g commitizen` and use `git cz` (instead of `git commit`) to commit your changes. ![Commitizen](https://github.com/commitizen/cz-cli/raw/master/meta/screenshots/add-commit.png) It is worth noting that release managers have the opportunity [squash and merge](https://help.github.com/articles/about-pull-request-merges/#squash-and-merge-your-pull-request-commits) using GitHub merge UI, in order to choose the right commit messages and keep commit log clean. When a release is performed, your CI environment will do the following: - Run all build and validation tasks defined by your build descriptor (ie GitHub Actions) - Create a GitHub tag, labelled after the version specified in `package.json` - Include a `CHANGELOG.md` file with a recap of all commits added since last release - Publish (on [npmjs.com/org/finos](https://www.npmjs.com/org/finos)) an updated version of the NPM package defined by `package.json` - Increase the version specified in `package.json` and push changes to `master` branch #### Release setup Travis CI must be configured with the following environment variables: - `GH_TOKEN`, used to create tags on GitHub - `NPM_TOKEN`, used to publish the npm package You can setup variables using [semantic-release-cli](https://semantic-release.gitbook.io/semantic-release/usage/ci-configuration#automatic-setup-with-semantic-release-cli) or the CI environment of your choice (see [how variables are set in GitHub Actions](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables)) Release configurations can also be [shared across npm projects](https://semantic-release.gitbook.io/semantic-release/usage/shareable-configurations). #### Advanced configurations Semantic release allows [additional configurations](https://semantic-release.gitbook.io/semantic-release/usage/plugins) to customise the release flow. --- ## Python [**Python**](https://www.python.org/) is an interpreted, object-oriented, high-level programming language with dynamic semantics. Packages are published on the [Python Package Index (pypi)](https://pypi.python.org/pypi), however the FINOS account is still empty, see [pypi.org/user/finos](https://pypi.org/user/finos/) . ### Publishing on Pypi Python packages can be easily installed using [pip](https://pip.pypa.io/); in order to publish a Python package to the Python Package Index, follow the [simple steps described on this blogpost](https://realpython.com/lessons/getting-started-pip-and-pypi/). That said, the Foundation is still working on a centralised, automated way to publish (and sign) Python packages so that they can be managed by Foundation Staff. ### Links - [Python Hacking style guide](https://github.com/symphonyoss/python-symphony/blob/master/HACKING.rst) - [Python semantic release](https://python-semantic-release.readthedocs.io/), automatic semantic versioning for python projects, including [Travis CI integration](https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/travis.html) --- ## Project Documentation FINOS project documentation is typically authored with Docusaurus and deployed with Netlify. This combination keeps docs easy to write in markdown, easy to review in pull requests, and easy to publish with preview environments. ### Advantages of a Centralized Documentation Strategy 1. Ease of use - Markdown syntax, simple local development, and easy configuration. 2. Easy to collaborate - Files are stored in a `docs/` folder in the GitHub repository, allowing anyone to submit a Pull Request. 3. Automated - Changes to `main` trigger a website deployment. 4. Branded - Enforces FINOS graphic guidelines across all websites. ### Getting Started with Project Documentation In order to add a website to an existing project, see the Docusaurus section below. If instead you are starting a new project, see the [FINOS project blueprint documentation](https://community.finos.org/docs/collaboration-infrastructure/#finos-project-blueprint). ### Examples of Docusaurus Project Documentation Websites - [FDC3](https://fdc3.finos.org) - [Open Source Readiness](https://osr.finos.org) - [VUU](https://vuu.finos.org) ### Docusaurus Docusaurus is a static website generator written in React, available open source under the Apache 2.0 license. It is technologically similar to Jekyll, which integrates tightly with GitHub Pages but lacks modern development support and local development tools. Given the significant adoption of Docusaurus within FINOS projects, it has become our go-to solution for building project documentation websites. If you're just getting started, use the [FINOS software project blueprint](https://github.com/finos/software-project-blueprint) repository template and follow the [blueprint documentation](https://community.finos.org/docs/collaboration-infrastructure/#finos-project-blueprint) to get started which includes a built-in Docusaurus website. The full Docusaurus documentation can be found on the [Docusaurus website](https://docusaurus.io/). #### Website dependency updates Website dependencies are excluded from OSV scans by default. If not, vulnerabilities negatively impact the health of the project as shown in [LFX Insights](https://insights.linuxfoundation.org) and [OSSF Scorecard](https://scorecard.dev/) even though the website is never actually shipped to the users. Note that [Docusaurus](https://github.com/facebook/docusaurus) patches often get published weeks or months after the vulnerable dependencies are detected. This means that automated dependency management tools like Dependabot are unable to quickly fix them and improve the project health score. If your repository already includes a Docusaurus website, copy [`osv-scanner.toml`](https://github.com/finos/software-project-blueprint/blob/main/website/osv-scanner.toml) into the `website` directory. Although not recommended, if you prefer to include website vulnerabilities in third-party scans, delete the [`osv-scanner.toml`](https://github.com/finos/software-project-blueprint/blob/main/website/osv-scanner.toml) file in the website root directory. #### Get Started in 5 Minutes :::info The following steps refer to Docusaurus 3.x and how it is used in conjunction with the [FINOS software project blueprint](https://github.com/finos/software-project-blueprint). ::: Ensure NodeJS and NPM are installed: ``` npm -v node -v ``` Create your repository from the template and start the website locally: 1. Click **Use this template** on https://github.com/finos/software-project-blueprint 2. Clone your new repository and run: ``` cd /website npm install npm start ``` #### Directory Structure Your project file structure should look something like this: ``` /project_root docs/ doc-1.md doc-2.md doc-3.md website/ .docusaurus/ node_modules/ src/ static/ css/ img/ docusaurus.config.js osv-scanner.toml package.json sidebars.js netlify.toml ``` See the Docusaurus 3 [project structure](https://docusaurus.io/docs/installation#project-structure). #### Adding and Editing Content Website pages are represented by Markdown files in the `docs/` folder (in Docusaurus 3, Markdown React files are also supported). The page `id` maps to the URL slug of the page; the title renders out as an `

` on the page. ``` --- id: example-doc title: Example Doc Page --- Add/Edit content here! ``` See the [Docusaurus docs](https://docusaurus.io/docs/docs-introduction) documentation page for more information. #### Navigation bar Add links to docs, custom pages, or external links by editing the `themeConfig` object in the `website/docusaurus.config.js` file: ``` themeConfig: { navbar: { title: `FINOS ${projectName}`, logo: { alt: 'FINOS Logo', src: 'img/favicon/favicon-finos.ico', }, items: [ /* you can add docs */ {to: 'docs/home', label: 'Docs', position: 'right'}, {to: 'docs/roadmap', label: 'Roadmap', position: 'right'}, {to: 'docs/team', label: 'Team', position: 'right'}, { /* you can add external links */ href: 'https://github.com/finos/', label: 'GitHub', position: 'right', } ], }, } ``` For more information, see the [Docusaurus Navbar Items](https://docusaurus.io/docs/api/themes/configuration#navbar-items) documentation. #### Sidebar The sidebar that is used to navigate the doc files in `docs/` folder is managed in the `website/sidebars.js` file. The sidebar links to each doc file via the `id` property set in the .md or .mdx file. ``` module.exports = { mainSidebar: { 'Main Menu': ["example-doc", "team", "roadmap"] }, } ``` For more details on how to configure the sidebar see the [Docusaurus Sidebar](https://docusaurus.io/docs/sidebar/) documentation. #### AI-readable documentation A production build can also write two text files for language models. `/llms.txt` lists every documentation page. `/llms-full.txt` contains the page text in one file. These files are documentation. They are not an MCP server. Install [`docusaurus-plugin-llms`](https://www.npmjs.com/package/docusaurus-plugin-llms) as a dev dependency with the package manager the website already uses. This repository uses Yarn (`yarn add --dev docusaurus-plugin-llms` from `website/`). The plugin declares the MIT license, which is a [Category A](/docs/governance/Software-Projects/license-categories) license. Register it in `website/docusaurus.config.js`. When the docs live outside the website folder, point `docsDir` at that directory and set `routeBasePath` to the URL prefix Docusaurus serves: ```js plugins: [ [ 'docusaurus-plugin-llms', { docsDir: [{ path: '../docs', routeBasePath: 'docs' }], excludeImports: true, }, ], ], ``` `excludeImports` removes MDX `import` lines from the generated text. `yarn build` or `npm run build` writes both files into the build output, and the links in `/llms.txt` use the site `url` from the Docusaurus config. MDX that uses `useBaseUrl` for a link or image loses that URL in `/llms-full.txt`. The visible words remain. Write links that need to survive in Markdown. Links inside `/llms-full.txt` are copied from the source, so a directory-relative link such as `(whitesource)` does not resolve from `/llms-full.txt`. Root-relative links such as `(/docs/governance)` do resolve when the file is hosted on the documentation site. #### Docusaurus Alternatives The [Accessibility Theme Builder](https://a11y-theme-builder.finos.org/) project website utilizes [MKDocs](https://www.mkdocs.org/) (specifically [Material for MKDocs](https://squidfunk.github.io/mkdocs-material/getting-started/)). Before Docusaurus, the FINOS Community also experimented with a few other solutions, which are worth mentioning for historical reasons: 1. [GitHub Wiki](https://help.github.com/en/github/building-a-strong-community/about-wikis) provides a great integration with code, as it's hosted as a git endpoint; however, Pull Requests are not available, therefore the collaboration mechanism can only be extended to the project team, which is a big limitation. Also, installing a local development environment [is not trivial](https://gist.github.com/suewonjp/7493de784f4a88c63d1810031609ee35) Its biggest advantage is the possibility to preview the changes via the GitHub web UI. 2. [Jekyll](https://jekyllrb.com/), the page generator engine used by GitHub Pages, which also supports templating; the downside of Jekyll is that the installation of a local development environment (Ruby) is hard. 3. [GoHugo](https://gohugo.io/), a generic static page generator written in Go, with a strong community and eco-system. ### Website Deployment #### Netlify Netlify is the preferred tool by FINOS when it comes to hosting websites, as it offers hosting and serverless backend services for web applications and static websites, along with seamless integration with GitHub and automatic preview capabilities that make it easier to review changes before they go live. #### Custom Domain Setup In order to deploy your website and get a custom subdomain configured, such as `fdc3.finos.org`, please email help@finos.org. #### Netlify Configurations In order to manage when/how Netlify creates previews a `netlify.toml` file can be placed in the root of the repository. For example the following configuration will trigger a preview only when it detects changes in the docs and website folders: ``` [build] ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../{docs,website}/" ``` See [this netlify.toml](https://github.com/finos/FDC3/blob/main/netlify.toml). ### Context7 [Context7](https://context7.com) brings a FINOS project's up-to-date docs into AI coding agents. Add the public repository once at [context7.com/add-library](https://context7.com/add-library). Choose GitHub, paste the repository URL, and submit. Anyone can add it. Context7 indexes the repository and assigns an ID such as `/finos/project`. The folder settings on that form are optional when the repository contains a `context7.json`. Commit that file at the repository root. Context7 reads it on a later refresh and reviews the title, description, and rules before using them. For a repository laid out like the [FINOS software project blueprint](https://github.com/finos/software-project-blueprint), index `docs/` and skip the Docusaurus app and discontinued material. Root-level Markdown, including `README.md`, is still indexed. Use `rules` for short facts an agent should follow, such as where contributions are described. Example `context7.json`: ```json { "$schema": "https://context7.com/schema/context7.json", "projectTitle": "Project Name", "description": "What the project does, in one or two sentences.", "folders": ["docs"], "excludeFolders": ["website", "archive"], "rules": [ "Follow this repository's CONTRIBUTING file before suggesting a code change." ] } ``` Claiming the library on Context7 is optional; it unlocks an admin panel and is separate from this file. Context7 refreshes a listed repository on its own. A Context7 GitHub Action is only needed when the project wants a refresh on every push to the default branch. See the [official Context7 guide](https://context7.com/docs/adding-libraries) for registration steps and repository configuration options. --- ## FINOS Contributor Cheatsheet ### Contributor License Agreement (CLA) and DCO Many FINOS projects use a **Contributor License Agreement (CLA)** or **Developer Certificate of Origin (DCO)** so the Foundation can distribute contributed code. Which mechanism applies depends on the project and stage; see [Contribution Requirements](/docs/governance/Software-Projects/contribution-compliance-requirements). **Code** contributions must follow the project’s policy (DCO sign-off, CLA via EasyCLA, or—for standards—CSLA). Other activities such as emails, issues, and meetings typically do not require CLA/DCO coverage. Where a project uses CLA, [EasyCLA](/docs/governance/Software-Projects/easycla) guides contributors through signing. Need an ICLA? Unsure if you are covered under an existing CCLA? Email [help@finos.org](mailto:help@finos.org) ### Contributing Issues #### Prerequisites * [ ] Have you searched for duplicates on GitHub Issues? A simple search for exception error messages or a summary of the unexpected behaviour should suffice. * [ ] Are you running the latest version? * [ ] Are you sure this is a bug or missing capability? #### Raising an Issue * Create your issue using GitHub Issues * New issues contain two templates in the description: bug report and enhancement request. Please pick the most appropriate for your issue, **then delete the other**. * Please also tag the new issue with either "Bug" or "Enhancement". * Please use [Markdown formatting](https://docs.github.com/en/get-started/writing-on-github) liberally to assist in readability. * [Code fences](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks) for exception stack traces and log entries, for example, massively improve readability. ### Contributing Pull Requests (Code & Docs) To make review of PRs easier, please: * Please make sure your PRs will merge cleanly - PRs that don't are unlikely to be accepted. * For code contributions, follow the existing code layout. * For documentation contributions, follow the general structure, language, and tone of the existing docs (if available) * Keep commits small and cohesive - if you have multiple contributions, please submit them as independent commits (and ideally as independent PRs too). * Reference issue #s if your PR has anything to do with an issue (even if it doesn't address it). * Minimise non-functional changes (e.g. whitespace). * Ensure all new files include a header comment block containing the [Apache License v2.0 and your copyright information](http://www.apache.org/licenses/LICENSE-2.0#apply). * If necessary (e.g. due to 3rd party dependency licensing requirements), update the `NOTICE` file (found in the project's root folder) with any new attribution or other notices #### Commit and PR Messages * **Reference issues, wiki pages, and pull requests liberally!** * Use the present tense ("Add feature" not "Added feature") * Use the imperative mood ("Move button left..." not "Moves button left...") * Limit the first line to 72 characters or less --- ## FINOS Maintainers Cheatsheet Welcome to the FINOS Maintainers Cheatsheet, the guide for new and experienced [FINOS Maintainers](https://github.com/finos/software-project-blueprint/blob/main/CONTRIBUTING.md#roles) on engaging with the [FINOS Community](https://www.finos.org/get-involved), [FINOS Team](https://www.finos.org/team) and [FINOS Governing Board](https://www.finos.org/governing-board) to drive project success. ### About FINOS [FINOS](https://finos.org) is part of [The Linux Foundation](https://linuxfoundation.org) and has the mission to enable a global community to create open source solutions for financial services. The [FINOS Knowledge Base](https://www.finos.org/knowledge-base) contains helpful resources on FINOS, the FINOS community and FINOS projects. Learn more in the [FINOS Governance](/docs/governance) and email [help@finos.org](mailto:help@finos.org) with questions or suggestions. ### FINOS Projects and Special Interest Groups (SIGs) FINOS [Open Source Software projects](/docs/governance/#open-source-software-projects), [Open Standards projects](/docs/governance/#open-standard-projects), and [Special Interest Groups (SIGs)](/docs/governance/#special-interest-groups) are at the very core of FINOS' mission to accelerate the use and development of open source software, standards, and practices to solve common challenges and drive innovation within the financial services industry. The open source software and standards projects hosted within FINOS cover a wide range of functions key to financial services including interoperability, cloud, infrastructure and data. The [FINOS Landscape](https://landscape.finos.org) provides an overview of all FINOS projects and Special Interest Groups, and the [FINOS GitHub organization](https://github.com/finos) hosts the code of all FINOS projects. ### Maintainer Role Each FINOS project and SIG has a community of [participants](https://github.com/finos/software-project-blueprint/blob/main/CONTRIBUTING.md#roles), also referred to as "contributors", and [maintainers](https://github.com/finos/software-project-blueprint/blob/main/CONTRIBUTING.md#roles). A **contributor** is anyone who submits a contribution to the project. Contributions include code & pull requests, 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](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization#repository-roles-for-organizations) to project repositories and may approve and merge contributions to the project. It is possible, and advised, that projects have multiple maintainers, in which case maintainers will elect one or two **lead maintainers**. The lead maintainer is the project's interface with the FINOS Team and Governing Board. Lead maintainers are responsible for communicating with the FINOS Team, Governing Board and Community on behalf of the project. The lead maintainer(s) are also accountable for steering project direction and prioritisation with the rest of the project community. They are also accountable for the quality of deliverables produced by the project community. FINOS Standards projects can also have [**editors**](https://github.com/finos/standards-project-blueprint/blob/main/GOVERNANCE.md#1-roles). ### MAINTAINERS.md file Every FINOS repository is expected to include a root-level `MAINTAINERS.md` file that clearly identifies the current project maintainers. The file gives contributors a consistent place to find who can review contributions, provide project guidance, and make or coordinate project decisions. Project maintainers are responsible for keeping the `MAINTAINERS.md` file accurate and up to date. Each maintainer entry should include the maintainer's GitHub username, name, and organization. An email address is optional. Keeping this information visible supports open governance, gives public recognition to the people and organizations sustaining the project, and helps FINOS and Linux Foundation projects maintain a transparent record of project leadership. All changes to the maintainer list must be managed openly: - Submit a Pull Request to `MAINTAINERS.md` for any maintainer addition, removal, or update. - If the project's governance requires a vote for maintainer changes, document or link to the vote outcome in the PR description or comments. - Use the PR history as the public audit trail for project leadership changes over time. Please email [help@finos.org](mailto:help@finos.org) whenever `MAINTAINERS.md` is updated with a change to maintainership. ### Maintainer responsibilities and available resources FINOS project maintainers are responsible for technical & subject matter oversight of the project, and for driving community growth and engagement. FINOS supports project maintainers and their project communities through: - **operational enablement & support**: GitHub, meeting infrastructure - **guidance and coaching on open source governance and best practices** - **project marketing**: coordination and production of webinars, newsletters, podcasts, participation in FINOS and external conferences and events, project merchandising/ swag FINOS project maintainers are encouraged to leverage the Linux Foundation's [LFX Project Control Center](https://docs.linuxfoundation.org/lfx/project-control-center), a platform that enables self-service configuration for governance, membership, IT, developer and collaboration tools, documentation, and community roles. The below table lists maintainers' responsibilities and available resources. Please email [help@finos.org](mailto:help@finos.org) to get in touch with the FINOS team with questions and suggestions. | Maintainer Responsibility | How FINOS supports you | |:---|:---| | **Grow project maturity and community** | Virtually all FINOS hosted projects are expected to strive towards, and ultimately attain, [Graduated status](/docs/governance/lifecycle-stages/graduated). The FINOS team supports projects in this journey through: **operational enablement**: see the [LFX Project Control Center](https://docs.linuxfoundation.org/lfx/project-control-center) **community marketing & engagement support**: Participation and/or feature your project in the [FINOS Newsletter](https://www.finos.org/newsletter), [FINOS Community Blog](https://www.finos.org/blog), [Open Source in Finance Podcast](https://podcasts.apple.com/us/podcast/finos-open-source-in-finance-podcast/id1512371068), [FINOS events](https://www.finos.org/hosted-events) including the [Open Source in Finance Forum (OSFF)](https://events.linuxfoundation.org/open-source-finance-forum/) [Request the creation](https://github.com/finos/community/issues/new?assignees=mcleo-d&labels=comms-channel-request&template=Communication_channel_request.md&title=) of a [FINOS Slack](https://finos-lf.slack.com/) Channel or enable GitHub Team Discussions for your FINOS Project or SIG. | | **Run Project Meetings** | Project maintainers are welcome to engage with their project community through project meetings. If they choose to do so, maintainers are responsible for creating meeting agendas and publishing meeting minutes. Email [help@finos.org](mailto:help@finos.org) for LFX PCC access, then [schedule and run meetings per FINOS Meeting Procedures](/docs/governance/meeting-procedures). [Publish the agenda and a link to the PCC AI summary from a GitHub Issue.](/docs/collaboration-infrastructure#meeting-minutes) | | **Maintain project leadership records** | Maintainers are responsible for keeping the root-level `MAINTAINERS.md` file accurate and up to date. FINOS supports this by providing a standard `MAINTAINERS.md` template, opening rollout PRs where possible, and helping projects resolve questions about format or process via [help@finos.org](mailto:help@finos.org). Any addition, removal, or update should be proposed through a Pull Request, with any required vote outcome documented or linked in the PR. | | **CI/CD** | Project maintainers are responsible for integrating Continuous Integration and Continuous Deployment into their FINOS project builds: [Use the FINOS Open Developer Platform for Continuous Integration and Deployment.](/docs/development-infrastructure/continuous-integration/intro/) | | **Documentation** | Maintainers are responsible for publishing project documentation from their project's GitHub Repositories to FINOS Project Websites. [Use Docusaurus and GitHub Actions for Publishing Project Documentation.](/docs/development-infrastructure/project-documentation#docusaurus) | | **Security** | Maintainers are responsible for preventing, discovering and responsibly disclosing Security Vulnerability Issues as they affect their projects, including [CRA escalation](/docs/governance/Software-Projects/cve-responsible-disclosure#cra-escalation-responsibilities) for actively exploited vulnerabilities and severe incidents [Use the FINOS Open Developer Platform for Project Security Vulnerability Scanning.](/docs/development-infrastructure/code-validation/whitesource) [Follow the FINOS responsible disclosure policy.](/docs/governance/Software-Projects/cve-responsible-disclosure) Escalate CRA-qualifying events to [steward@linuxfoundation.org](mailto:steward@linuxfoundation.org) and CC [security@finos.org](mailto:security@finos.org) | | **MAINTAINERS.md** | Maintainers are responsible for maintaining a MAINTAINERS.md file in their project repository's root directory. The MAINTAINERS.md file should list all maintainers and their contact information. | --- ## Governing Board Election Procedure FINOS uses a ranked-choice instant-runoff voting process for elections of Gold and Silver representatives on the Governing Board. These are the rules by which the results are tabulated. (Platinum representatives are not elected, but are appointed by individual Platinum members.) I. Single-Winner Elections In any contest for exactly one office conducted by ranked choice voting,each validly cast ballot shall be initially counted as one vote for the candidate at its highest continuing ranking or as an exhausted ballot. If a candidate has more than half of the total votes counting for candidates, that candidate is elected and the tabulation is complete. Otherwise, the tiebreaker score is calculated and tabulation proceeds in rounds. Each round shall proceed sequentially as follows: 1. If two or fewer continuing candidates remain, the candidate with the greatest number of votes is elected and the tabulation is complete. Otherwise, the tabulation continues to paragraph 2. 1. The candidate with the fewest votes is defeated. Votes for the defeated candidate shall cease counting for the defeated candidate and shall be added to the totals of each ballot’s next-ranked continuing candidate or counted as exhausted ballots, and a new round begins with paragraph 1. II. Multiple-Winner Elections In any contest for more than one office conducted by ranked choice voting, each validly cast ballot shall be initially counted as one vote for its highest-ranked continuing candidate or as an exhausted ballot. The election threshold and tiebreaker score shall be calculated. Tabulation shall then proceed sequentially as follows: 1. If the number of continuing candidates whose vote totals exceed the election threshold is equal to the number of seats remaining to be filled, those candidates are elected and the tabulation is complete. If the number of continuing candidates is equal to or less than the number of seats remaining to be filled, then all continuing candidates are elected and the tabulation is complete. Otherwise, the tabulation continues to paragraph 2. 1. If no candidate has a vote total that exceeds the election threshold, the tabulation continues to paragraph 3. If at least one continuing candidate has a vote total that exceeds the election threshold, then the continuing candidate with the highest vote total is elected. The number of surplus votes for such candidate shall be calculated. The surplus fraction for such candidate shall be calculated. The new transfer value of each vote cast for such candidate shall be calculated. Votes for such candidate shall be added, at their new transfer values, to the totals of each ballot’s highest-ranked continuing candidate or counted as exhausted ballots, and a new round begins with paragraph 1. In all subsequent rounds, any candidates elected under this subsection shall have vote totals equal to the election threshold. 1. The candidate with the fewest votes is defeated. Then, if the number of continuing candidates is equal to the number of seats remaining to be filled, all continuing candidates are elected,and the tabulation is complete. Otherwise, votes for the defeated candidate shall cease counting for the defeated candidate and shall be added, at their current transfer values, to the totals of each ballot’s next-ranked continuing candidate or counted as exhausted ballots, and a new round begins with paragraph 1. III. Ties FINOS shall resolve prospective ties between candidates using a "backward" approach: 1. The vote count at the previous round is used to break the tie. Suppose we are selecting a candidate to eliminate at round 4 and Alice and Bob are tied for last place. The tie would be broken by comparing Alice and Bob's vote counts at round 3. If they are still tied at round 3, then round 2 is used and so forth. 2. If the candidates are tied at all rounds, then the tie is broken randomly. IV. Definitions For the purposes of this policy, the following terms have the following meanings: * “Can be mathematically eliminated” means a candidate is part of a group of candidates such that: * if a candidate is in the group, then every continuing candidate with equal or fewer votes is also in the group; * the total votes for all candidates in the group is less than the number of votes for any continuing candidate not in the group; * for a single winner contest, there are at least two continuing candidates not in the group. * for a multi winner contest, the total votes for all candidates in the group is less than the election threshold; * for a multi winner contest, there are at least as many continuing candidates not in the group as there are seats remaining to be filled. * “Continuing candidate” means any candidate that has not been defeated or elected. * “Election threshold” means the number of votes sufficient for a candidate to be elected in a multi winner contest. The election threshold is calculated by dividing the total number of votes counting for continuing candidates in the first round by the sum of one plus the number of offices to be filled, rounding up to four decimal places. * “Exhausted ballot” means a ballot that is not counted for any continuing candidate for one or more of the following reasons: * It does not rank any continuing candidates; * its highest continuing ranking contains an overvote; or * it includes two or more consecutive skipped rankings prior to its highest continuing ranking. * “Highest continuing ranking” means the highest ranking for any continuing candidate. * “Overvote” means a voter has ranked more than one candidate at the same ranking. * “Ranking” means the number assigned by a voter to a candidate to express the voter’s choice for that candidate. A ranking of “1” is the highest ranking followed by “2” and then “3” and so on. * “Round” means an instance of the sequence of voting tabulation beginning with paragraph 1 of Section I (Single-Winner Elections) or Section II (Multiple-Winner Elections). * “Skipped ranking” means a voter has left a ranking blank and ranks a candidate at a subsequent ranking. * “Surplus” means a positive difference between a candidate’s vote total and the election threshold. * “Surplus fraction” means the number equal to a candidate’s surplus divided by that candidate’s vote total, calculated to four decimal places, ignoring any remainder. * “Transfer value” means the proportion of a vote that a ballot will contribute to its highest continuing ranking. Each ballot begins with a transfer value of 1. If a ballot transfers from an elected candidate with a surplus, it receives a new transfer value. The new transfer value of such a ballot is calculated by multiplying the surplus fraction of the elected candidate by the ballot’s current transfer value, calculated to four decimal places, ignoring any remainder. --- ## FINOS Funding Documents FINOS is a directed fund of the Linux Foundation governed by the following documents publicly available on the [FINOS website governance page](https://finos.org/governance): - [FINOS Charter](https://www.finos.org/hubfs/FINOS%20Charter%20(2024-12-09).pdf) - [FINOS Participation Agreement (Not for Execution)](https://www.finos.org/hubfs/FINOS%20Foundation%20-%20Participation%20Agreement%20(rev.%2011-26-2024)%20-%20Not%20For%20Execution.pdf) --- ## Community Code of Conduct ### Overview The Fintech Open Source Foundation ("FINOS" or the "Foundation") community is comprised of professionals and volunteers from all over the world, working in many different capacities including writing code, leading working groups, managing events, and more. Diversity is one of our strengths, but it can sometimes give rise to miscommunication and conflict. To ensure that all of our contributors feel welcome and valued, our code of conduct establishes clear expectations for participants in the Foundation's work. It is not intended to serve as an exhaustive list of prohibited behavior, but rather, a set of principles for maintaining a healthy and inclusive community. This code of conduct applies to all activities managed by FINOS. This includes the Foundation's developer pod, mailing lists, Jira, Confluence, GitHub resources, conference calls, in-person events, and any other forum established or managed by the Foundation for community collaboration. In some cases, violations of this code outside of the Foundation's scope may affect a person's ability to participate in our community. The code of conduct also applies to every member of the Foundation community, including Foundation staff, members, project maintainers, volunteers, event participants, sponsors, and vendors. ### Reporting Violations If you observe or are subject to a violation of these rules at a Foundation event, please report the matter to any FINOS representative on-site. Please report any other code of conduct violations by emailing legal@linuxfoundation.org. We are committed to protecting the safety and privacy of anyone who reports a violation. ### Code of Conduct * **Be friendly and patient.** * **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability. * **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language. * **Be respectful.** People working together will inevitably disagree or become frustrated with one another at times, but conflict is no excuse for bad behavior or personal attacks. A community where people feel uncomfortable or threatened is not a productive one. Be respectful of one another and those outside our community who interact with us. * **Be careful in the words that you choose.** Conduct yourself professionally. Be kind to others. Refrain from all forms of harassment, including: * Violent threats or language directed against another person. * Discriminatory jokes and language. * Posting sexually explicit or violent material. * Posting (or threatening to post) other people's personally identifying information ("doxing"). * Personal insults, especially those using racist or sexist terms. * Unwelcome sexual attention. * Advocating for, or encouraging, any of the above behavior. * **Repeated harassment of others**. In general, if someone asks you to stop, then stop. * **Be understanding.** Strive to resolve disagreements constructively. Our contributors come from different backgrounds and have different perspectives. If you disagree with someone, seek to understand their perspective and share yours respectfully. --- ## Our Collaborative Principles FINOS technical projects are free to determine their own governance so long as it is consistent with [FINOS policies](https://finos.org/governance). However, projects are expected to adhere to best practices for open source collaboration. The practices documented here help to ensure that FINOS projects are well-documented, inclusive, free of intellectual property issues, and responsive to their communities. ### Project materials and communication Open source projects function best when their code, documentation, and roadmaps are readily accessible and up-to-date, and when the project maintainers are responsive to the community. FINOS projects are expected to: * maintain all project artifacts (source code, standards documents, etc.) in a public repository * maintain a public, current list of issues/tasks and their priority * respond in a timely manner to issues raised by the community via the project's issue tracker * ensure all commits and Pull Requests are clearly tracked against an issue * respond to all pull requests in a timely manner, clearly communicating any issues * participate actively in the project's chosen communications forum (e.g. mailing list, slack instance, etc.) * provide an opportunity for all community members to participate in conversations or meetings about the project roadmap and priorities * rely only on free and open source (or at least free-to-use) tools and file formats, to the extent possible * communicate major events, such as significant design changes, to the community clearly and in advance ### Project governance Projects should ensure that governance procedures are well-documented and followed by the team. Project governance documents should clearly state: * the requirements for a community member to gain committer or other leadership privileges * acceptance criteria for pull requests, including any style or quality guidelines (see the [CONTRIBUTING.md template](https://github.com/finos/software-project-blueprint/blob/main/CONTRIBUTING.md) from our software project blueprint for an example) Please see the [software project governance template](https://github.com/finos/software-project-blueprint/blob/main/CONTRIBUTING.md) or [standard project governance template](https://github.com/finos/standards-project-blueprint/blob/master/Readme.md) for recommended starting points. ### IP compliance FINOS maintains policies and procedures for ensuring that all contributed code is appropriately licensed. Depending on the project, contributors use DCO or CLA; where a project uses CLA, [EasyCLA](Software-Projects/easycla) flags contributions that are not yet covered. When EasyCLA flags a pull request, project maintainers should not merge the pull request until the contributor is properly covered. See our [Contribution Requirements](Software-Projects/contribution-compliance-requirements) for more information. --- ## Individual Supporter Program The Individual Supporter program recognizes individuals who are not affiliated with FINOS corporate members but have made significant contributions to FINOS collaborative projects. Individuals who meet the criteria below may apply to join the program and receive members-only benefits. To apply, please email membership@finos.org and let us know how you meet the criteria below. ### Criteria * Applicants must have made a significant contribution to FINOS collaborative work during the preceding year, defined as any of the following: * Maintainership of a FINOS project * Commits accepted to a FINOS project * Active participation in a FINOS standards project (determined by reference to the policy of the project) * 1+ year of service as a [FINOS ambassador](https://www.finos.org/finos-ambassador-program) through participation in marketing activities, speaking at events, organizing meetups, or writing blog posts * Membership must be renewed annually and applicants must meet the above criteria as of the date of renewal. ### Benefits * Acknowledgment on the FINOS website and newsletter as a Individual Supporter * Attendance at select members-only events * Free or discounted tickets to select paid FINOS events * Access to the members-only lists and communications ### List of individual supporters Our valued individual supporters are listed in our [FINOS Members page](https://www.finos.org/members#at-large). --- ## Project Meetings :::caution To ensure FINOS meetings are conducted in a manner that is fair and respectful to all participants, FINOS aligns to The Linux Foundation **privacy policy that excludes the use of external AI chatbots and scribing services** participating in any public or private virtual meetings hosted by FINOS. Provided no objections are raised, meeting hosts may use LF recording and transcription services to facilitate minutes production. ::: This document describes requirements and recommendations for holding meetings of FINOS projects (including SIGs, working groups, and other bodies). Note that individual projects may have their own meeting requirements, in which case those should be followed except where they conflict with any FINOS policy. ### Self-serve meetings in LFX PCC FINOS project meetings are scheduled in the Linux Foundation [LFX Project Control Center (PCC) Meetings](https://docs.linuxfoundation.org/lfx/project-control-center/v2-latest-version/collaborations/meetings) tool. Once you have access, you can schedule, update, and cancel your projects Zoom meetings in PCC. How to use the product is in the LFX documentation linked below; this page covers FINOS access, policy, and hosting expectations. #### Request access PCC access is not granted automatically. Project maintainers and designated meeting hosts **must** email [help@finos.org](mailto:help@finos.org) and ask to be added to their FINOS project in LFX PCC before they can manage meetings. Include: * Your name and the email address on your Linux Foundation ID * The FINOS project for which you need access to schedule and manage meetings You need a [Linux Foundation ID](https://openprofile.dev/) to sign in to [PCC](https://projectadmin.lfx.linuxfoundation.org/). After FINOS staff grant access, search for your project, then open **Collaboration** → **Meetings**. If you cannot see your project, cannot schedule a meeting, or need help with an existing series, email [help@finos.org](mailto:help@finos.org). #### LFX Meetings documentation Use these LFX guides for the product itself: * [Meetings overview](https://docs.linuxfoundation.org/lfx/project-control-center/v2-latest-version/collaborations/meetings) — find meetings, calendar view, recordings, and transcripts * [Schedule a meeting](https://docs.linuxfoundation.org/lfx/project-control-center/v2-latest-version/collaborations/meetings/scheduling-a-meeting) — one-off and recurring meetings, participants, public calendar, recording, and host-key sharing * [Join a meeting](https://docs.linuxfoundation.org/lfx/project-control-center/v2-latest-version/collaborations/meetings/joining-a-meeting) — LFX join page, guests, public calendar, and attendance * [Find your host key](https://docs.linuxfoundation.org/lfx/my-profile/meetings/find-your-host-key) — claim host in Zoom from [My Meetings](https://openprofile.dev/my-meetings) * [Manage meetings](https://docs.linuxfoundation.org/lfx/project-control-center/v2-latest-version/collaborations/meetings/manage-meetings) and [cancel meetings](https://docs.linuxfoundation.org/lfx/project-control-center/v2-latest-version/collaborations/meetings/delete-meetings) * [Meetings FAQs](https://docs.linuxfoundation.org/lfx/project-control-center/v2-latest-version/pcc-faqs/meetings-faqs) #### Expectations when scheduling a meeting * Hosts **should** schedule meetings at least 7 days in advance, preferably at a time that works for most participants. * Hosts **should** use Zoom via LFX PCC unless all members are able and prefer to use another system. * Hosts **should** share the host key with at least one backup host in PCC so the call can proceed if the primary host is unavailable. * Hosts **must not** select the **Board** meeting type unless the meeting is an official FINOS Governing Board meeting. * LF recording, transcripts, and Zoom AI summaries in PCC may be used when no objections are raised. Do not admit third-party AI meeting bots or scribing services. * Hosts **must** set **Meeting Settings** as follows (**See screenshot below**): * **Show in Public Calendar** — on, so the meeting appears on the [FINOS Community Calendar](https://calendar.finos.org) * **Restrict to invited users** — off * **Early Join Time (minutes before start)** — `10` * **Send reminder email to participants** — optional * **Auto-record from meeting start** — on * **Generate transcript** — on * **Auto-upload recordings to YouTube** — off * **Enable Zoom AI** — on * **Review AI summary before publishing?** — on * **Where should users see the link(s) to AI Summary and Recordings?** — **PCC only** ![LFX PCC Meeting Settings with the FINOS required options. Send reminder email to participants is optional.](/img/pcc-meeting-settings.png) ### Prepare and circulate an agenda * Before each meeting, hosts **must** create a GitHub issue listing the topics to be discussed and decisions to be made, and circulate that issue via the group's preferred communication channel. * Use the [meeting minutes template](https://github.com/finos/software-project-blueprint/issues/new?template=meeting_minutes.yml). See [Meeting Minutes](/docs/collaboration-infrastructure#meeting-minutes) for the GitHub workflow. * Do not use the GitHub issue to record attendance. ### Keep minutes * Hosts **must** keep minutes of meetings, capturing: * For each agenda item: * A brief summary of the matter discussed (one sentence is often enough). * Any significant positions/proposals put forward (one sentence each is often enough). * A record of any decisions made or actions taken, including a record of the vote (i.e. votes in favor, votes against, and abstentions). * Any action items assigned, including the assignee and the deadline (if any). * Minutes **must not** attribute any statement to an individual or organization without their express prior approval. This is to ensure that people feel free to speak candidly. * Minutes **should** be concise records of the important parts of the meeting. They should not be an exhaustive transcript. (See [this example](https://github.com/finos/FDC3/issues/481).) * LFX PCC produces a Zoom AI summary automatically. Hosts **should** use that summary to capture minutes. Before publishing, hosts **must** anonymize it: remove names and any other details that would attribute a statement to an individual or organization without their express prior approval. Then **publish** the summary in PCC. An unpublished summary is not a minutes record. * Hosts **must** post a public link to meeting minutes after the meeting. The GitHub agenda issue is that public record. Once the AI summary is published, add the summary URL to the issue. Viewing the summary in PCC requires an LF login; the GitHub issue remains the link anyone can open. ### Run the meeting * Hosts **should** claim the Zoom `host` role. See [Host the Zoom meeting](#host-the-zoom-meeting) below. * Hosts **must** ensure that the meeting adheres to the [LF Antitrust Policy](https://www.linuxfoundation.org/legal/antitrust-policy). * Hosts **must** ensure the [FINOS Code of Conduct](https://community.finos.org/docs/governance/code-of-conduct/) is adhered to at all times and remove anyone from the call who does not adhere to it. * Hosts **should** display the [Antitrust Policy summary slide](/Compliance-Slides/Antitrust-Compliance-Slide.pdf) at the beginning of the meeting. * Standards project hosts **should** display the [standards project compliance slides](/Compliance-Slides/Standards-Project-Compliance-Slides.pdf) at the beginning of the meeting. * Hosts **should** ask new participants to identify themselves with a quick introduction and their affiliations. If an attendee is not able to be identified they **should** be removed. * Hosts **should** run the meeting according to the following best practices: * Ensure a good audio connection. Laptop audio is often worse than a phone call. * Minimize background noise. Mute yourself and (if necessary) other participants when you or they are not speaking. * Join and claim host before the call is scheduled to start. * Start the meeting 5 minutes after the scheduled start to give people time to join. * Keep the meeting to the agenda. Move off-topic discussions to the agenda for the next meeting, or the mailing list. * If a discussion becomes unproductive, move on. Ask the participants to send their proposals via issues/pull requests, on the mailing list or as agenda items for future meetings. * End the meeting on time, even if you don't get through the agenda, so those with other appointments do not miss important discussions. * If a host cannot attend a call and there is no backup host available, the call **must** be cancelled with at least 24 hours notice and the community notified via its preferred communication channel. Cancel the occurrence in PCC; if you do not yet have PCC access, email [help@finos.org](mailto:help@finos.org). ### Call votes as needed Hosts **should** call a vote on any agenda item requiring one, according to the voting procedures of the group. ### Host the Zoom meeting Hosts **should** claim the host role after joining so they can manage participants, waiting room, and screen sharing. Get the host key from PCC or from [My Meetings](https://openprofile.dev/my-meetings) and follow [Find your host key](https://docs.linuxfoundation.org/lfx/my-profile/meetings/find-your-host-key). The host key is available starting one hour before the call. After claiming host, FINOS highly recommends enabling the waiting room and disabling participant screen sharing: 1. Click the **Host tools** icon in the Zoom toolbar and toggle on **Enable Waiting Room**. 2. Click **Host tools** again and, under **Allow All Participants To**, toggle off **Screen Share**. --- ## Project Branding Guidelines One of the first steps any open source project takes is choosing a name (and possibly a logo). Project names and logos (referred to collectively as "marks" in this document) should be distinctive and should avoid incorporating the names and logos of third parties and third-party products. As with other products and services, the names and logos of open source projects (including nonprofit projects) are the project's trademarks. A well-chosen mark can confer upon the project the exclusive right to use that mark under applicable trademark laws, as well as the right to exclude others from using the same or confusingly similar marks. Without taking care, however, it is easy to choose a mark that cannot be protected, or that may infringe upon another's rights. FINOS does not register all its projects' marks as trademarks, but the rules for selecting marks that can be registered are still useful guidelines when choosing a brand. This guide is intended to help FINOS projects select good marks and limit the potential for conflicts. This guidance is not a substitute for legal advice. If you have questions about a name or logo you would like to use for your project, please contact FINOS at legal@finos.org. ### Guidelines for Choosing Appropriate Names and Logos When choosing a mark, projects should follow these guidelines to ensure that your project's marks do not infringe the rights of third parties or create liability for the project or FINOS. Projects should **avoid** marks that: * Imply a particular level of service or might otherwise create liability (e.g. supported, secure, fastest, etc.) * Are so general that they imply the project is the only, or standard, solution for certain area of technology, especially if no wide support exists amongst FINOS Members and contributors * Do not include references to other products or (third-party) projects, except where explicitly allowed by the owner, or in a way that makes clear that there's no endorsement by or affiliation with the owner If you have any questions about whether a particular mark meets FINOS's criteria, please contact us at legal@finos.org. ### Choosing Marks that Can Be Registered as Trademarks FINOS does not register trademarks for all project marks, and does not require that projects choose marks that can be registered as trademarks. However, for some projects it may be appropriate to file for trademark protection. This section and those that follow contain guidelines for selecting a mark that is suitable for registration. This is how the US Patent and Trademark Office defines a trademark: > * A trademark is generally a word, phrase, symbol, or design, or a combination thereof, that identifies and distinguishes the source of the goods of one party from those of others. > * A service mark is the same as a trademark, except that it identifies and distinguishes the source of a service rather than goods. A trademark protects the name or logo of a product or service. Trademarks exist as much to protect consumers as to protect their owners: they assure consumers that products associated with a mark come from the owner of that mark. Trademarks are different from copyrights, which protect original works of authorship, and patents, which protect inventions. #### Characteristics of a Strong Trademark Because trademarks are intended to uniquely associate a product with its producer, a trademark must be **distinctive** to qualify for protection (and registration) under trademark laws. That is, the mark must be sufficiently different from other marks used in the same market or industry that it adequately distinguishes one product from another. To ensure that a mark is distinctive, projects should **avoid**: * **Generic** marks that employ words or designs commonly used to refer to a class of products generally. For example, "Software" as a name for computer software would be generic. * **Descriptive** marks that merely describe the product. Descriptive marks are similar to generic marks, but include a broader category of marks. For example, "Fast Sort" for a data-sorting library is descriptive. Unlike generic marks, it is possible for descriptive marks to be registered, if through their use in commerce they come to take on "secondary meaning" in the minds of consumers (i.e. to become uniquely associated with the product in the relevant market) and therefore acquire distinctiveness. However, this result is not guaranteed and descriptive marks should therefore generally be avoided. * **Common words or phrases**. The more common, the more likely it's used on products of all kinds, and when you get to your trademark search, you're likely to get lots of results, including in relevant markets. The **strongest** marks are those that do not directly describe the product. They are generally categorized (in order from strongest to weakest) as: * **Fanciful** marks bearing no meaning except to designate the product. A common example is "XEROX" for copiers. * **Arbitrary** marks may contain words with an independent meaning, but with no connection to the product. For example, "APPLE" for computers. * **Suggestive** marks suggest qualities or characteristics of the product but do not directly describe them like a descriptive mark does. For example, "WIKIPEDIA" suggests a wiki website containing an encyclopedia, but in the form of a made-up portmanteau. By selecting a name or logo that meets these criteria, projects are more likely to end up with a distinctive mark that can be protected from confusingly similar uses. #### Doing a Trademark Search Choosing a mark that fits the criteria above isn't always enough. If someone else is already using the mark (or a confusingly similar one) in a related market, the mark may infringe that third-party mark (or at least be impossible to register or protect). Before settling on a mark, it's important to ensure there are no directly conflicting marks already out there. A thorough search typically requires the help of an experienced trademark attorney. However, you can do an initial search yourself to ensure there are no obvious conflicts. This usually involves: * A few **internet searches** on the mark and other relevant words (e.g. "foobar computer software") to see if there are others using the mark for similar goods or services. * Searching the **USPTO [TESS Database](http://tess2.uspto.gov/)** to see if the same or similar marks are registered for similar goods or services in the US. The TESS search interface can be a little intimidating -- [this guide](https://www.uspto.gov/sites/default/files/documents/TM-FederalTrademarkSearching-GettingStarted-handout.pdf) includes some useful tips for running a complete search. It may be necessary to narrow your search to the classes of goods and services that your product falls under. Each trademark registration must specify one of [45 internationally recognized classes](https://www.uspto.gov/trademark/trademark-updates-and-announcements/nice-agreement-current-edition-version-general-remarks) of goods and services. If your initial search turns up too many results across all classes, limiting your search to relevant classes (like Class 9 for software, or Class 42 for software services, or Class 36 for financial services) can make the results easier to comb through. * Searching trademark databases in other jurisdictions where the mark is likely to be used: * European Union: https://www.tmdn.org/tmview/welcome * United Kingdom: https://www.gov.uk/search-for-trademark * Switzerland: https://www.swissreg.ch/srclient/faces/jsp/start.jsp * Benelux (Belgium, Netherlands, and Luxembourg): https://www.boip.int/en/trademarks-register * For more international databases, see the WIPO database: https://www.wipo.int/amc/en/trademark/output.html No trademark search can 100% exclude the possibility of a competing mark, but by taking these steps, you can avoid choosing a name with obvious conflicts. When brainstorming names, it's often a good idea to come up with several potential options, because one or more is likely to be knocked out by your initial search. #### When to Register a Trademark FINOS does not register the trademarks of all of its projects, as the costs would be prohibitive. If you'd like to discuss registration, please contact us at finos.org and we can discuss whether it's appropriate in your project's case. ## How does FINOS protect a project brand? FINOS generally endeavors to monitors usage of FINOS project brands and the FINOS brand itself for compliance with the [FINOS trademark guidelines](/governance-docs/Trademark-Guidelines.pdf). Additionally, if the FINOS team becomes aware of alleged technical misrepresentations on a FINOS project in the public press, it will work with the Project maintainers to validate veracity of the statements and take actions as needed. Please email legal@finos.org if you'd like to report misuse of FINOS projects brands. --- ## Lifecycle introduction ## Introduction FINOS projects are categorized according to the FINOS Project Lifecycle: each project is required to clearly display their Lifecycle Stage in the form of a badge in their README.md. The Project Lifecycle is maintained by the [FINOS Technical Oversight Committee](https://github.com/finos/technical-oversight-committee) and serves as a recognition of governance transparency, community health, in addition to functional (features) and non functional (security, best practices, etc) maturity of the project with respect to its stated goals and roadmap. > **NOTE:** The FINOS Lifecycle was updated in 2026 to reflect evolution of the foundation and now aligns closely with the [CNCF maturity model](https://github.com/cncf/toc/blob/main/process/README.md). ## Why is the Project Lifecycle needed? * **For Consumers:** The lifecycle is designed to help users easily determine which projects are appropriate for their use, whether it be experimentation or production use. * **For Maintainers:** The lifecycle gives FINOS maintainers a roadmap for progressing their projects towards increasing levels of maturity. * **For FINOS Staff:** The lifecycle gives FINOS staff a way to offer access to different benefits (and therefore incentives) to projects which are more appropriate for their lifecycle stage. ## FINOS Lifecycle Stages Projects in FINOS can be in one of the following lifecycle stages: | Badge | Lifecycle Stage Details | What does it signal to consumers? | | ----- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-forming.png) | [Forming](/docs/governance/lifecycle-stages/forming) | In this stage, projects can optionally start for a limited time in a **Member-only private repo** to gauge viability and interest across Members before being opened to the world. | | ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-labs.png) | [Labs](/docs/governance/lifecycle-stages/labs) | This stage is the default entry point for all FINOS projects which **are in an initial exploratory or experimental phase** while still hosted in a neutrally governed space overseen by FINOS. | | ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-incubating.png) | [Incubating](/docs/governance/lifecycle-stages/incubating) | This stage is for projects with high potential in early growth phase in terms of their functionality, maturity, and community sustainability. | | ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-graduated.png) | [Graduated](/docs/governance/lifecycle-stages/graduated) | This stage is the highest maturity stage, for active projects with healthy and diverse contributor and adopter communities | | ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-archived.png) | [Archived](/docs/governance/lifecycle-stages/archived) | This stage is for projects that, while potentially still highly valuable, are no longer actively maintained. | Please review individual lifecycle stage pages for detailed information about what each stage represents for consumers, what are the criteria and ongoing requirements for projects to be in a lifecycle stage and instructions for maintainers how to apply for each stage. ## FINOS Lifecycle Governance Per [TOC responsibilities](https://github.com/finos/technical-oversight-committee/blob/main/operations/governance.md#responsibilities), the [TOC](https://github.com/finos/technical-oversight-committee/) is responsible for: - Maintaining and evolving all lifecycle stages definitions - Approve lifecycle transitions (or new contributions) to the Incubating, Graduated and Archived stages - resolve any potential dispute that may occur between project maintainers and who is proposing an archival transition The FINOS Staff is responsible for: - Accepting new projects into Labs stage according to the [FINOS Labs](/docs/governance/lifecycle-stages/labs) requirements --- ## Foundation Governance This space provides an overview of the Foundation's governance: ### Membership FINOS is a membership organization within the [Linux Foundation](http://linuxfoundation.org/). We have four tiers of corporate membership (Platinum, Gold, Silver and Associate), each with different rights and obligations under the Foundation's [Funding Documents](funding-documents). Please refer to the FINOS website for more information on [FINOS members and membership benefits](https://www.finos.org/membership-benefits) or reach out to [membership@finos.org](mailto:membership@finos.org). Individuals who have made significant contributions to FINOS projects can join our [Individual Supporter program](/docs/governance/individual-supporter-program) to be recognized for their contributions and receive certain members-only benefits. **NOTE**: Membership is NOT required to contribute to existing FINOS projects. Software contributors must comply with the [FINOS code contribution compliance requirements](/docs/governance/Software-Projects/contribution-compliance-requirements), and participants in Standards Projects must comply with the [FINOS Standard Governance IP requirements](/docs/governance/#open-standard-projects). Only FINOS members can propose new FINOS projects, as outlined in [Community Governance](#community-governance) below. ### Governing Board The Foundation is overseen by a [Governing Board](https://www.finos.org/governing-board) composed of member representatives and led by FINOS Executive Director. The Governing Board is composed of Platinum Representatives, each appointed by a Platinum member; up to five Gold Representatives, elected by the Gold Members voting as a class; and one Silver Representative, elected by the Silver Members voting as a class. FINOS uses [ranked-choice voting](board-election) to tabulate elections. The Foundation's day-to-day operations are run by the [FINOS team](https://finos.org/team). ### Technical Oversight Committee The FINOS Technical Oversight Committee (TOC) is FINOS's technical governing body. It works closely with the FINOS team and the Governing Board to provide technical oversight for projects in the FINOS portfolio (read more [about TOC responsibilities](https://github.com/finos/technical-oversight-committee/blob/main/operations/governance.md)). The TOC is composed of [12 members](https://github.com/finos/technical-oversight-committee/#membership) from FINOS members and the broader community, each serving a two-year term (read more [about the voting process](https://github.com/finos/technical-oversight-committee/blob/main/operations/processes/elections/elections.md)). ### Policies The following policies apply to all FINOS members and activities: * The [Charter](funding-documents) is the Foundation's constitution. It sets out our mission, members' rights and responsibilities, the authority and procedures of our Governing Board and its committees, and other Foundation policies. * The [Participation Agreement](funding-documents) is the agreement that all of our members sign to join FINOS. It sets membership fees and terms and binds members to the terms of the [Charter](funding-documents). FINOS members must also be members of the Linux Foundation (at any level) and remain in compliance with LF's [Good Standing Policy](https://www.linuxfoundation.org/good-standing-policy). There is no requirement for membership to participate in the FINOS Community, but only members can propose new projects. * The [Community Code of Conduct](/docs/governance/code-of-conduct) is the set of principles that participants in the Foundation's collaborative work are expected to abide by to maintain a healthy and inclusive community. * The [IP Policy](/governance-docs/IP-Policy.pdf) contains rules related to the intellectual property of FINOS, our members, and contributors. It includes policies for the licensing of contributions to FINOS projects, licensing of FINOS projects to third parties, and licensing of contributions to FINOS technical standards. The policy also requires all contributors to FINOS projects to sign either a [Corporate Contributor License Agreement](/governance-docs/CCLA.pdf) (for corporate/institutional contributors) and [Individual Contributor License Agreement](/governance-docs/ICLA.pdf) (for individual contributors whose contributions are not owned by their employer). FINOS uses [EasyCLA](/docs/governance/Software-Projects/easycla) to simplify the processes of executing CLAs and managing contributors. * The [Trademark Guidelines](/governance-docs/Trademark-Guidelines.pdf) list the Foundation's trademarks and set out our policies for appropriate use of FINOS project marks. * The Linux Foundation [Antitrust Policy](https://www.linuxfoundation.org/legal/antitrust-policy) applies to all FINOS collaborative projects and prohibits all potentially anticompetive conduct. ### Community Governance FINOS is home to two kinds of [collaborative projects](https://landscape.finos.org): **open source software projects** and **open standards projects**. Most FINOS projects are open source software projects. Projects are self-governing and may propose amendments to their governance rules (consistent with FINOS policies and the [open source definition](https://opensource.org/docs/osd)), subject to Governing Board approval. FINOS also provides default governance templates as a starting point. FINOS also hosts **Special Interest Groups (SIGs)** which are forums where community members sharing an interest in a certain topic discuss ideas, compare experiences, and consider common solutions (which may or may not take the form of new open source software or standards projects). All FINOS projects and SIGs are expected to observe the FINOS [Collaborative Principles](/docs/governance/collaborative-principles), [Meeting Procedures](/docs/governance/meeting-procedures) and recommended to follow [Branding Guidelines](/docs/governance/project-branding-guidelines). For a list of our projects see the [FINOS project landscape](https://landscape.finos.org). ### Open Source Software Projects FINOS is home to dozens of open source software projects. Any FINOS member (and only FINOS members) may propose a new project or sponsor a project from an outside contributor. Project proposals are reviewed and approved by the TOC in consultation with the Governing Board. Please refer to the [contribution process](/docs/governance/Software-Projects/contribution) if you'd like to propose a new software project or contribute to an existing one. The [default governance policy](https://github.com/finos/software-project-blueprint/blob/main/CONTRIBUTING.md) for FINOS open source software projects follows a governance-by-contribution model. Project maintainers have the last word on technical matters, reaching decisions by consensus if possible and by vote if necessary. Anyone who has made a substantial contribution (of any kind) to the project may be nominated to become a maintainer. ### Open Standard Projects Projects producing open standards require different IP rules detailing how to establish and running Open Standard Projects (see [FINOS contribution requirements](/docs/governance/Software-Projects/contribution-compliance-requirements)). New FINOS standards projects are recommended to use the [Community Specification](https://github.com/finos/standards-project-blueprint) process for standards development (earlier standards projects are governed by the, now deprecated, detailed IP rules set out in the [FINOS IP Policy](/governance-docs/IP-Policy.pdf)). All participants in standards projects are bound by these rules, even if their only contribution is participation in project meetings. This is to ensure that any specification or other materials produced by a standards project may be licensed appropriately to all standard users and implementers. Please create a [new Standard Project issue](https://github.com/finos/community/issues/new?template=standards_project_contribution.yml) if you'd like to propose a new standard project (FINOS Members only). The FINOS Governing Board approves new Open Standard Projects. ### Special Interest Groups Special Interest Groups can be proposed by any FINOS Member (and only by FINOS Members) and are approved by the Governing Board, including a Charter and initial SIG chair. Over time the SIG can decide to vote in a new Chair or the Board can appoint one. The Charter may also be updated from time to time with updates published publicly. Read more for [a list of current SIGs](/docs/governance/special-interest-groups) and how to propose a new SIG. All participants in SIGs are subject to [FINOS Policies](#policies) and [Community Governance](#community-governance) including complying with [Antitrust Policy](https://www.linuxfoundation.org/legal/antitrust-policy) and [Community Code of Conduct](https://www.finos.org/code-of-conduct). Documents produced or contributed as part of the SIG will be contributed and made available under CC-BY-4.0. ### Project Lifecycle and Steering #### Project Lifecycle Software projects follow the [Project Lifecycle](/docs/governance/project-lifecycle), a useful tool for consumers and contributors to quickly evaluate maturity, activity, and quality. Projects may begin in either the "Labs" or "Incubating" state, graduate to "Graduated", and finally may move to the "Archived" state (from either Labs, Incubating, or Graduated) if they are no longer actively developed. The TOC approves lifecycle transitions following objective criteria detailed for [Incubating](/docs/governance/lifecycle-stages/incubating) and [Graduated](/docs/governance/lifecycle-stages/graduated) projects. Some projects may optionally start in a time-bound pre-incubation stage called *Formation*, which is typically restricted to FINOS Members or at the discretion of the project lead. [Forming projects](/docs/governance/project-lifecycle) might not be publicly visible until entering Incubation when they will be fully open sourced. #### Project Metrics Live metrics of Project activity and contributions across all FINOS collaboration systems are publicly available in [FINOS Project Activity Dashboard](https://metrics.finos.org). #### Project Governing Board Reporting Periodically data about the health, activity, and progress of projects is reported to the Governing Board. Reports are largely generated automatically out of the [FINOS Project Activity Dashboard](https://metrics.finos.org) and provided to the TOC for review before being passed along to the board. The Governing Board, TOC and FINOS team use these reports to determine which projects need additional attention, which should be considered for archiving, etc. Every year, the Governing Board identifies a few "strategic initiatives" to receive extra attention from the FINOS team during an agreed time period, with the goal of supporting growth and progression through the Project Lifecycle. Focus projects should be prepared to provide more detailed progress reports to the Board at the next Board meeting. --- ## CSLA Within FINOS, an Open standard project is a project chartered primarily to produce technical standards specifications, rather than software. Standards projects follow a different set of processes than software projects, to account for the different intellectual property requirements of standards. The purpose of these rules is to ensure that all contributions to a standard are appropriately licensed and that the final published standard may be implemented freely by FINOS members and the community at large. FINOS standards projects follow the [Joint Development Foundation](https://www.jointdevelopment.org/)'s [Community Specification](https://github.com/CommunitySpecification/1.0) process, which is a mature suite of workflows, policies, and templates for collaborating on a standard specification via source code management system such as git & GitHub. Each standards project will also be goverened by the additional policies and procedures set out in its charter. This document summarizes the requirements for establishing, joining, and running standards projects, but it is not comprehensive. Anyone involved in running a standards project should review the Community Specification documentation carefully in addition to referring to this information. Note that FINOS has made a few customizations to the Community Specification process for its own needs, so please refer to the [FINOS Standards Project Blueprint](https://github.com/finos/standards-project-blueprint/), which contains the full Community Specification documentation together with those customizations. The rest of this document links to the Blueprint. ### Establishing a standards project In order to contribute an existing standards project, or to start a new standards project, a [FINOS member](https://finos.org/members) must submit a standard project proposal, using the [FINOS standard project proposal template](https://github.com/finos/community/issues/new?template=standards_project_contribution.yml), and identifying the project's scope, roadmap, and [maintainers](https://community.finos.org/docs/finos-maintainers-cheatsheet/). ### Getting the project started After a standards project is approved, FINOS will set up a repository for the standard project within the FINOS GitHub organization. Project maintainers will then copy the [FINOS Standards Project Blueprint](https://github.com/finos/standards-project-blueprint) into the project repository and follow the directions in the [Getting Started](https://github.com/finos/standards-project-blueprint/blob/main/GETTING_STARTED.md) file to finalize the repository setup. ### Requirements of standards project participants #### IP licensing requirements Contributions to FINOS standards projects are governed by the [Community Specification License](https://github.com/finos/standards-project-blueprint/blob/main/LICENSES/SPECIFICATION-LICENSE) (the "CSL"). The CSL specifies the copyright and patent rights licensed by contributors to implementers of the specification, as well as the other terms applicable to contributions. Generally, contributors authorize anyone to produce specification-compliant implementations of: (1) any draft version of the specification that they contributed to, and (2) any final specification approved by the project (except for patent claims properly excluded by the contributor). Every participant to a FINOS standards project must agree to the [Community Specification Contributor License Agreement 1.0](https://github.com/finos/standards-project-blueprint/blob/main/governance-documents/CS_Contributor_License_Agreement.md) ("CSLA") as it applies to that project. Participants contributing on behalf of their employers must have permission to agree to the CSLA on behalf of their employer. By agreeing to the CSLA, participants agree to the terms of the following project policies: * [Community Specification License](https://github.com/finos/standards-project-blueprint/blob/main/LICENSES/SPECIFICATION-LICENSE) (described above) * [Community Specification Governance Policy](https://github.com/finos/standards-project-blueprint/blob/main/GOVERNANCE.md) (setting out the project governance rules) * [Community Specification Contribution Policy](https://github.com/finos/standards-project-blueprint/blob/main/CONTRIBUTING.md) (setting out the workflow for making contributions to the project) * [Community Specification Code of Conduct](https://github.com/finos/standards-project-blueprint/blob/main/CODE_OF_CONDUCT.md) (setting out the rules for appropriate participant behavior) The CSLA also requires that participants represent that their contributions are original (or appropriately licensed by third parties) and that they have permission to enter the CSLA on behalf of their employer, if applicable. The above is only a summary of the obligations of participants. Each participant should review the CSLA, and the other policies it references, with their own counsel to understand how these terms apply to their participation. #### Community Specification License Patent Exclusion Rules When a participant contributes to a draft specification, the participant agrees to license to implementers of the specification any of its patent claims that apply to that draft specification. Likewise, when the project issues an approved specification, all contributors to that specification agree to license any claims that apply to that approved specification. These licenses apply to any claims practiced by the specification as a whole, not merely to the individual participant's contributions. However, the CSL (in Section 3) gives contributors an opportunity to exclude specified claims from its licensing commitments by issuing an "exclusion notice" within 45 days of its contribution to a draft specification, or from the project's adoption of a draft specification as an approved specification. Thus, if a participant learns that a specification it has contributed to incorporates patented claims it is unwilling to license, it may withhold a license for those claims. #### Specific rules for software If a standards project incorporates software (e.g. example code or reference implementations), whether in the specification itself or as supporting material, that software is subject to the same licensing requirements as other FINOS software projects, i.e. it must be licensed under the Apache License unless the FINOS Governing Board approves the use of another license. ### Meeting procedures for standards projects and working groups At the beginning of each meeting of a standards project, the project leaders should remind participants that their participation is subject to the Community Specification License and the Linux Foundation Antitrust Policy. Here are slides that can be used: * [Download as PPTX](/Compliance-Slides/Comm-Spec-Compliance-Slides.pptx) * [Download as PDF](/Compliance-Slides/Comm-Spec-Compliance-Slides.pdf) * [View as Google Slides](https://docs.google.com/presentation/d/1qVhtj3OoPxfPSIPAbR8mQl3z3P9Ai2IH2CIzv1ReBoM/edit#slide=id.g41c8fed37d_0_0) --- ## Contribution Requirements ### Overview {#overview} This page describes **intellectual property and licensing expectations when onboarding a new FINOS software project or open standard project**—not routine contributions to an existing repository (follow that project’s `CONTRIBUTING` file and its DCO, CLA, or CSLA setup). For **software** projects, after onboarding FINOS places the **technical charter** at the repository root as **`technical-charter.pdf`** (that exact filename). It reflects mission, goals, and responsibilities from the contribution process. **Open standard** projects use the [Standards Project Blueprint](https://github.com/finos/standards-project-blueprint) for Community Specification documents and CSLA instead of this PDF. Before you proceed, be familiar with: - [Contributing to FINOS](/docs/governance/Software-Projects/contribution), including [project governance](/docs/governance/project-lifecycle) and lifecycle stages. - [CLA vs. DCO](https://osr.finos.org/docs/bok/artifacts/clas-and-dcos#cla-vs-dco) in the FINOS Open Source Readiness (OSR) handbook. FINOS **software** projects establish contributor rights through a **Developer Certificate of Origin (DCO)** or **Contributor License Agreements (CLAs)**. Per OSR, **FINOS projects use DCO by default**; a project may use **CLA** when requested by the maintainers and coordinated with FINOS. **Labs** projects **always** use **DCO**. - For how DCO maps to CLA and when each applies, see OSR: [CLA vs. DCO](https://osr.finos.org/docs/bok/artifacts/clas-and-dcos#cla-vs-dco). - For configuring DCO checks on GitHub, see [DCO on GitHub](/docs/governance/Software-Projects/dco). FINOS **standards** (specification) projects use the **Community Specification License** and [**CSLA**](/docs/governance/Software-Projects/csla) (Community Specification Contributor License Agreement), not the generic software-project DCO/CLA path. ### Contributor license agreement (or CLA){#contributor-license-agreement} The FINOS IP policy specifies that projects that adopt CLA should use FINOS contributor license agreements derived from the commonly used Apache-style CLA template. FINOS uses [EasyCLA](https://lfx.linuxfoundation.org/tools/easycla) ([direct access](https://lfcla.com)) so contributors can sign the appropriate documents when a repository requires CLA. EasyCLA is maintained by the Linux Foundation. It is designed to support open source communities by: * Recognizing a contributor’s signature across FINOS repositories that use the same EasyCLA configuration. * Letting contributors sign as individuals or be covered under a Corporate CLA when employed by a firm. * Letting companies designate a CLA Manager who can update approval configuration in the [EasyCLA Organization Dashboard](https://organization.lfx.linuxfoundation.org/). * Letting companies authorize employee usernames individually, or by email domain or GitHub organization affiliation. There is no cost to signing the FINOS CLA. Please note that this is different from [membership in FINOS](https://www.finos.org/membership-benefits). If your organization relies upon our projects, [please become a member](https://www.finos.org/members). Membership dues help fund the FINOS project ecosystem. If you change jobs after contributing to the Foundation under your previous employer's CCLA, please notify [help@finos.org](mailto:help@finos.org) so that we can ensure that an appropriate CLA is in place with you or your new employer. For signature workflows, CLA Managers, and enabling EasyCLA on a repository, see the dedicated [EasyCLA](/docs/governance/Software-Projects/easycla) page. ##### Individual and Corporate CLA When a software project uses CLA, contributors typically use an **Individual Contributor License Agreement (ICLA)** or a **Corporate Contributor License Agreement (CCLA)**. For the distinction between them, see [Two types of CLA](https://osr.finos.org/docs/bok/artifacts/clas-and-dcos#two-types-of-cla) on OSR. ### License Information {#license-information} All Foundation projects must include certain license information and copyright notices. If you are contributing a new project, you must include `LICENSE`, and `NOTICE` files, as described below. If you are contributing to an existing project, you may need to add information to the `NOTICE` or (optionally) `CONTRIBUTING` file. #### The LICENSE file A `LICENSE` file must be present at the root of each project, and must contain the text of the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt). #### The NOTICE file A `NOTICE` file must be present at the root of each project, and must contain the copyright notices of each copyright holder who has contributed to the project. If you are contributing to an existing project, you should add (or update) your copyright notice in the `NOTICE` file. A sample `NOTICE` file (Markdown format) is provided in the [FINOS Software project blueprint](https://github.com/finos/software-project-blueprint). It must also contain any other attributions required by third-party dependencies (see below). You should use this template for your `NOTICE` file (from the [FINOS Software project blueprint](https://github.com/finos/software-project-blueprint/blob/main/NOTICE)). Add a `Copyright` line for each copyright holder who has contributed to the project: ``` {PROJECT_NAME} - FINOS Copyright {YYYY} - {CURRENT_YEAR} {NAME_OF_COPYRIGHT_OWNER} {EMAIL_OF_COPYRIGHT_OWNER} This product includes software developed at the Fintech Open Source Foundation (https://www.finos.org/). {OTHER_NOTICES} ``` #### The CONTRIBUTING file The `CONTRIBUTING` file contains basic instructions to prospective contributors about how to make a contribution to the project – submitting a CLA, filing issues, making pull requests, etc. A sample `CONTRIBUTING.md` file (Markdown format) is provided in the [FINOS Software project blueprint](https://github.com/finos/software-project-blueprint). Project leads are free to revise to fit the practices and style of the project, but references to the Foundation's contribution requirements must be included. While a `CONTRIBUTING` file is not required, we strongly encourage you to add one to your repository as early as possible. Please note that Github will prompt this content when a user creates an issue or pull request, you can read more on [GitHub Contributing Guidelines](https://github.com/blog/1184-contributing-guidelines). #### Source code license headers For [Graduated](/docs/governance/lifecycle-stages/graduated) projects, it's recommended that each source code file should include a license header comment. Most projects use the standard Apache-style header. Note that all copyright notices should go into a separate single `NOTICE.md` file at the root level (i.e. same level as `README.md` and `CONTRIBUTING.md`) of the GitHub/GitLab repository. ``` SPDX-License-Identifier: Apache-2.0 Copyright {YYYY} FINOS {PROJECT_NAME} contributors - see NOTICE file Licensed under the Apache License, Version 2.0 (the "License"); 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. ``` If space is at a premium, you are welcome to use an abbreviated version like the following: ``` SPDX-License-Identifier: Apache-2.0 Copyright {YYYY} FINOS {PROJECT_NAME} contributors - see NOTICE file ``` #### SPDX information We encourage project teams to place a [SPDX-format](https://github.com/david-a-wheeler/spdx-tutorial#spdx-files) `LICENSE.spdx` file in the root of each project. SPDX is a standard for describing machine-readable license information about open source projects. For more information on SPDX, please see the [SPDX website](https://spdx.org/). See below for a basic example `LICENSE.spdx` file. For a tutorial on adding SPDX information to a project, [see here](https://github.com/david-a-wheeler/spdx-tutorial/blob/master/README.md). ``` SPDXVersion: SPDX-2.0 DataLicense: CC0-1.0 Creator: {NAME_OF_COPYRIGHT_OWNER} PackageName: {PROJECT_NAME} PackageOriginator: {NAME_OF_COPYRIGHT_OWNER} PackageHomePage: https://github.com/finos/{PROJECT_SLUG} PackageLicenseDeclared: Apache-2.0 ``` ### Third-Party Code Compliance {#third-party-code-compliance} If your contribution includes any third-party open source code, the license for that code must permit its use within an Apache-licensed project, and the Foundation's use of the code must comply with the terms of the third-party license. #### Identifying acceptable licenses All Foundation projects must be licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) and the license for any third-party code must be compatible with this requirement. The Foundation [categorizes open source licenses in the same way as the Apache Software Foundation](/docs/governance/Software-Projects/license-categories): - **Category A licenses** have similar terms to the Apache License. Contributions to the Foundation can include (or depend upon) code licensed under Category A licenses. - Examples: common variants of the BSD and MIT licenses; the Apache License. - **Category B licenses** impose restrictions on downstream use of the third-party code, but permit the code to be included in an Apache-licensed project. Typically, these are "weak copyleft" licenses requiring that modifications to the third-party code be licensed "reciprocally" under the same license. Contributions can include (or depend upon) Category B code, but if the code itself is included with the contribution, you should include a notice in the `CONTRIBUTING` file as described below. - Examples: the CDDL, EPL, and MPL licenses. - **Category X licenses** impose restrictions that prevent the code from being included in an Apache-licensed project. Because all Foundation projects must be Apache-licensed, the Foundation does not accept contributions with Category X dependencies. - Examples: most proprietary licenses; any version of the GPL, LGPL, or AGPL; Creative Commons Non-Commercial and No-Derivatives licenses. Projects teams are expected to ensure that the license of each dependency meets these requirements at all times; committers can expedite this by carefully researching each dependency before adding it. Because all incompatibly licensed dependencies must be removed before the Foundation can accept a contribution, contributors should also take care to avoid them during their development on a fork. #### Including required third-party notices Depending how your contribution uses third-party open source software, you may need to add notices to the project you're contributing to. **If your contribution contains third-party code directly** (i.e. not via an import or similar reference resolved by the build system or interpreter) you must include a copy of the applicable license and preserve any copyright notices, license information, disclaimers, and similar notices in the third-party code. You should also add a notice in the following form to the project's file: `This project includes code from SuperWidget 1.2.3, which is licensed under a BSD-style license. For details, see lib/superwidget/.` If you have a `LICENSE.spdx` file in your repository, you should also update the PackageLicenseDeclared setting to use the appropriate SPDX license expression for your "mixed license" repository. **If your contribution contains Category B-licensed code directly**, you must also add a notice in the following form to the project's `NOTICE` file: `This project contains source code for SuperWidget 1.2.3, which is licensed under the Mozilla Public License, version 1.1. For details, see lib/superwidget/.` The purpose of this notice is to make contributors aware that their modifications to the Category B code will be governed by the terms of the Category B license. **If the third-party license requires specific notices**, you must add them to the `NOTICE` file. For example, some open source licenses require that you include a description of any modifications made to the third-party code. #### Validating license and notice information When you make a contribution, the Foundation attempts to validate compliance with these requirements automatically using a variety of tools [made available by FINOS](/docs/development-infrastructure/code-validation/intro). However, no automated tool can resolve these questions definitively, so we depend upon our contributors and project teams to ensure compliance with this policy at all times. --- ## Contributing to FINOS There are several ways you can contribute to our existing projects and SIGs, and [FINOS Members](https://finos.org/members) can propose new projects for contribution. Take a look at the diagram below for an overall picture of how contributions flow into FINOS: ![FINOS Contribution Process](/finos-contribution-process.png) ### Contribution of use cases and ideas to a Special Interest Group (SIG) If you are looking to contribute a use case or idea, start by searching if there already is [a special interest groups](/docs/governance/special-interest-groups) in that area. SIGs are meant to be arenas for like minded professionals to identify common challenges, pain points and opportunities to then be solved collaboratively in the open. ### Contribution to an existing FINOS project {#contribution-of-code-to-an-existing-finos-project} The easiest way to engage is to contribute code, documentation, test cases, requirements, issues and pull requests, etc. to [projects that are currently within the Foundation](https://landscape.finos.org). Before contributing to a project, community members are encouraged to familiarize themselves with a project by doing any or all of the following: - [Engage](/docs/journey/engage) with the project community via mailing list/slack/github - Review the project specific roadmap, area of focus, typically contained in a project Readme.md. - Review [good first issue/help wanted issues in the FINOS GitHub organization](https://github.com/search?q=org%3Afinos+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) > **NOTE**: Forms of contribution that require a contributor to make git commits, and in turn, request those to be merged via pull requests, must comply with the [Contribution Requirements](Contribution-Compliance-Requirements.md) in place within FINOS. ### Contribution of a new FINOS project or SIG {#contribution-of-a-new-FINOS-project-or-SIG} #### FINOS Membership requirement While everyone can contribute to existing projects, only [FINOS Members](https://finos.org/members) can contribute new projects to FINOS. This ensures sustainability of our ecosystem. If you are not a FINOS Member, consider: 1. Inviting a FINOS Member to be a maintainer of your project and submit on your behalf. You can reach out to our community via our [community@finos.org](mailto:community@finos.org) mailing list to solicit interest. 2. Consider becoming a [FINOS Corporate Member](https://www.finos.org/membership-benefits) to contribute to the sustainability of the ecosystem > **OPTIONAL**: [FINOS Platinum Members](https://finos.org/members) can also request a so called [Forming stage](/docs/governance/lifecycle-stages/forming). If you are a member and want to explore project formation, please reach out to [FINOS Member Success](mailto:membersuccess@finos.org). #### Pre-Work: Contribution Fitness First off, you want to evaluate whether the contribution is suitable for a Foundation-hosted open source project, in terms of long term expectations and desire to build a diverse Community of adopters and contributors. Projects contributed to the Foundation generally start in [Labs stage](/docs/governance/lifecycle-stages/labs), which sets out a set of criteria and maintenance expectations. Contributors are encouraged to evaluate the checklist and ensure they are willing to achieve those criteria before, during and after contribution. For more mature projects, at the time of contribution contributors will have an option to evidence compliance with later stages and request the [Technical Oversight Committee](https://github.com/finos/technical-oversight-committee) to award [Incubating](/docs/governance/lifecycle-stages/incubating) or [Graduated](/docs/governance/lifecycle-stages/graduated) stage. #### Step 1: Submit a contribution proposal By default, a new software project contribution enters FINOS at the **[Labs](/docs/governance/lifecycle-stages/labs)** stage. See [Project lifecycle](/docs/governance/project-lifecycle) for how stages work. Contributors may instead ask the [Technical Oversight Committee](https://github.com/finos/technical-oversight-committee) to recognize **[Incubating](/docs/governance/lifecycle-stages/incubating)** or **[Graduated](/docs/governance/lifecycle-stages/graduated)** stage when the contribution already meets the criteria for that stage. Draft a proposal to be reviewed by the FINOS team. Please use the available templates for: - [Open source software project](https://github.com/finos/community/issues/new?template=software_project_contribution.yml) - [Open standard / specification project](https://github.com/finos/community/issues/new?template=standards_project_contribution.yml) - [Special Interest Group](https://github.com/finos/community/issues/new?template=special_interest_group_contribution.yml) *Note:* For software projects if you select the "Incubating" or "Graduated" stage, you will be asked to complete a follow-up issue containing stage-specific criteria, utilizing either the [Project Incubation](https://github.com/finos/community/issues/new?template=project_incubation.yml) or [Project Graduation](https://github.com/finos/community/issues/new?template=project_graduation.yml) forms. This will create a new issue on the [FINOS Community Repository](https://github.com/finos/community/issues) and kick off the process. The proposal is meant to cover the following: 1. **Business problem**: the business problem that the proposed contribution solves. 2. **Proposed solution**: how the proposed contribution solves that business problem. For software projects, include a detailed description of the software and its functionality. 3. **Tentative roadmap**: a description of the short and medium term goals and phases of the project, and what success looks like for this project 4. **Current state**: a summary of the contribution's history and status. Include information about the contribution's maturity and roadmap. 5. **Existing materials**: links to and descriptions of any existing project materials (e.g. GitHub repositories). If any materials are currently private, please describe them in detail. The FINOS team will reach out to request access to private materials in order to evaluate them. 6. **Development team**: current contributors, including full name, affiliation, work email address, and GitHub.com username where available. 7. **Contributor commitment**: describe the resources you'll commit to supporting the contribution should it be accepted by the Foundation, in line with the Lifecycle Stage you are applying for. This might include developer time (in FTEs), marketing support, Foundation membership, etc. The **technical charter** sets forth the mission, goals, and responsibilities of the project. When a **software** project contribution is approved, FINOS publishes it at the **root of the project GitHub repository** as **`technical-charter.pdf`**. The information you supply in your proposal will match what will appear in that document. To maximize the chances of being accepted, you should provide evidence in your submission of compliance with the criteria and commitment to fulfill ongoing maintenance requirement listed in the [Project Lifecycle](/docs/governance/project-lifecycle). > **TIP**: To review previous contribution proposals (to see examples, or to see if someone has contributed something similar, etc.) you can search our [Github contribution issues history](https://github.com/finos/community/issues?q=is%3Aissue+label%3Acontribution+). #### Step 2: Socialization Once the issue is raised, maintainers should email directly the [community@finos.org](mailto:community@finos.org) ([subscribe here](mailto:community+subscribe@finos.org)) and [TOC](mailto:toc@lists.finos.org) to outline your contribution idea and link to the previously created contribution issue). A simple note pointing to the Github contribution issue and encouraging the FINOS Community and Members to post their support / feedback on the issue will go a long way here. Below a template provided for you as a starting point to socialize your proposed contribution. ``` Subject: New proposed contribution to FINOS: - we need your feedback! Body: Dear FINOS Community, I am excited to announce that we have just submitted the contribution of . You can find all the details of the contribution at . As the TOC gears up to review the contribution we would love to see your feedback and questions on the issue to express your interest in adopting or even better contributing to the project. Even a thumbs up would be very much appreciated. Also please don't hesitate to reach out to me at if you have any questions. Thanks in advance for your consideration! ``` > **Note**: while everyone is welcome to contribute to existing projects, **only [FINOS Members](https://finos.org/members) can propose new projects**. If you are not a Member this step is particularly important to identify a Member who could become a sponsor for your project, by being listed in the initial maintainers. #### Step 3: Approval Once the FINOS team has validated the contribution proposal for completeness, the contribution must go through an approval phase, for alignment with the scope and objectives of the Foundation, viability, perceived interest within the FINOS community. Particularly: - Special Interest Groups and Open Standards, the Governing Board will review and approve the contributions either via an email vote or at the next available meeting. - For software project contributions, the [Technical Oversight Committee (TOC)](https://github.com/finos/technical-oversight-committee/) will review and approve the contributions. #### Step 4: IP review & Transfer of Contributions Once a contribution is approved, the Foundation will perform an audit to ensure the contribution is consistent with the [FINOS contribution requirements](Contribution-Compliance-Requirements.md). The main areas covered are: ##### Trademark - If the chosen project name and existing logo are found to be risky choices from a trademark standpoint (e.g. they clash with existing marks), the project will be requested to select a new name that does not conflict with any existing marks - If the contributor holds a trademark or the project name has been previously used in the public domain (therefore potentially granting the contributor [common law trademark rights](https://www.uspto.gov/learning-and-resources/trademark-faqs#type-browse-faqs_1967), the contributor will be requested to transfer the project trademark to the Linux Foundation by completing a [contribution agreement](/governance-docs/The.Linux.Foundation.--.Form.of.Trademark.Assignment.20221202.pdf). This will allow FINOS to neutrally steward the project consistently with our [Trademark Guidelines](/governance-docs/Trademark-Guidelines.pdf). ##### Intellectual property The project will be required to: - Have appropriate [DCO or CLA coverage](/docs/governance/Software-Projects/contribution-compliance-requirements) for each maintainer - Comply with third-party licenses and the [FINOS acceptable Apache-compatible license policy](/docs/governance/Software-Projects/license-categories). - Comply with FINOS notice requirements for IP notices, contributor attribution, etc - this can happen right after the contribution (see [incubating criteria](/docs/governance/lifecycle-stages/incubating)) #### Step 5: Transfer and Review of Contribution Materials Following successful IP and trademark compliance, the FINOS infrastructure team will work with the contributing organization to transfer existing code and other materials to the project's collaboration infrastructure (e.g. its GitHub repository, project web site, and/or wiki space) and set for permissions for the initial list of maintainers. This can happen by giving access to an existing DVCS repository to the FINOS team or sending the FINOS team an archive containing the code to be contributed. See [Code transfer options](#code-transfer-options). It's during this step as well that [code validation and scanning](/docs/development-infrastructure/code-validation/intro) of the code base will be performed, any build processes set up and configured, and the various components documented in the `Project Tooling` section configured and set up for the project, at which point the rest of the Foundation's infrastructure will be available to the project contributors moving forward to use to develop, test and release the project. #### Step 6: Contribution Announcements Once the transfer and review is complete, it's time to announce the contribution and garner attention and additional contributions from the FINOS community. In order to do so: We encourage project leads to [email announce@finos.org](mailto:announce@finos.org) - see a couple of [good examples](https://groups.google.com/a/finos.org/forum/#!topic/announce/2LoANL9lzB0) or use the template below and don't be shy! ``` Subject: New Project announcement: now Open Source in FINOS Body: Dear FINOS Community, I am excited to announce that was successfully contributed to FINOS and hosted at . The most current release is , available for download at . Documentation is available at and you can reach out to the project team at . Your feedback, issues, and contributions are more than welcome. See for more information on how to contribute and here's a few area where we could use help Thanks to the FINOS Community for a warm welcome! ``` Besides the technical announcement on list, the FINOS team will recommend to coordinate marketing announcements including: - Blog posts to announce the contribution on [finos.org/blog](https://www.finos.org/blog) - you can contact our [Marketing](mailto:marketing@finos.org) to propose an article - Social media announcements - you can reach out to [marketing@finos.org](mailto:marketing@finos.org) to ask for our support in promoting the contribution - For substantial contributions, especially of those with multiple contributing orgs, FINOS may choose to support contribution announcement with a press release. Contact [marketing@finos.org](mailto:marketing@finos.org) if you think a press release is warranted and co-promotion from your organization. ### Code transfer options {#code-transfer-options} There are several ways in which contributors can transfer their project's code to the FINOS infrastructure team during contribution: #### GitHub.com repository (recommended) Use [GitHub's transfer ownership capability](https://help.github.com/articles/about-repository-transfers/) to move it over to the project's GitHub organization. To do this, the contributor will need to temporarily add one of the project's GitHub organization owners (e.g. the project [maintainer](https://community.finos.org/docs/finos-maintainers-cheatsheet/)) as an admin on the source repository, so that they can initiate the transfer. Once the code has been transfered, the contributor will be able (and is encouraged) to remove the project's GitHub organization owner from the repository. FINOS recommends this approach as it has the unique benefit of preserving the full commit & pull request histories, the project's issue list, wiki and GitHub pages, and more. Some important notes: 1. When transferring a repository, its issues, wiki, stars, and watchers are also transferred (read more details [about repository transfers](https://help.github.com/articles/about-repository-transfers/)) 2. When transferring a private repository, all forks will be disabled, until [marked as public](https://help.github.com/articles/making-a-private-repository-public/); they will also be disconnected from the upstream repository, therefore it is strongly advised to push all changes to an upstream branch, before transferring the code #### GitHub.com repository where it is not possible to temporarily configure someone else as an admin Perform a double transfer: 1. Transfer ownership of the repository to a personal ("user") account on GitHub (see the [GitHub documentation](https://help.github.com/articles/transferring-a-repository-owned-by-your-organization/) for details) 2. Follow the steps described above for transferring a GitHub.com repository to the project #### GitHub Enterprise repository Perform a copy, transfer, and freeze: 1. Copy the repository into a personal ("user") account on GitHub (see [Adding locally hosted code to GitHub](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github)) 2. Follow the steps described above for transferring a GitHub.com repository to the project 3. Delete or freeze (e.g. disable access, make read-only, etc.) the repository in your GitHub Enterprise installation, to prevent accidental modifications to the wrong repository. #### Other Source Code Management (SCM) repository Perform an import, transfer, and freeze: 1. Use the [GitHub importer](https://help.github.com/articles/about-github-importer/) to import the repository into a personal ("user") account on GitHub (see the [GitHub documentation](https://help.github.com/articles/importing-a-repository-with-github-importer/) for details) 2. Follow the steps described above for transferring a GitHub.com repository to the project 3. Delete or freeze (e.g. disable access, make read-only, etc.) the repository in your SCM installation, to prevent accidental modifications to the wrong repository. #### Source code snapshot Snapshotting the code and providing it to the FINOS Infra team in an archive file (.zip, .tar.gz, etc.) can also work. This is the recommended approach if you wish to truncate the commit history prior to contribution. #### Do-It-Yourself (DIY) If you wish to populate your repository yourself, the FINOS Infra team should create an empty repository in the project's GitHub organization (as described above), and then configure the contributing team as owners and committers with appropriate access. ### Have questions? If you'd like help, don't hesitate to reach out by email to [help@finos.org](mailto:help@finos.org) or ask the wider community with a note to [community@finos.org](mailto:community@finos.org). --- ## DCO on GitHub FINOS software projects use the [Developer Certificate of Origin](https://developercertificate.org/) (DCO) by default. Contributors certify their commits by adding a `Signed-off-by` line to each commit message (for example with `git commit -s`). For background on DCO compared with CLA, see [CLA vs. DCO](https://osr.finos.org/docs/bok/artifacts/clas-and-dcos#cla-vs-dco) on OSR. This page describes how to **enforce DCO on GitHub** using **[DCO2](https://github.com/cncf/dco2)**—the GitHub App that checks pull requests for valid sign-offs (a successor to the classic DCO bot). ### Install DCO2 1. [Install and configure the DCO2 GitHub App](https://github.com/apps/dco-2) for your FINOS organization or for the repositories that should enforce DCO. 2. After installation, DCO2 reports a **status check** on each pull request indicating whether every commit includes a valid `Signed-off-by` line. See the [DCO2 documentation](https://github.com/cncf/dco2) for details on check output, remediation commits, and optional `.github/dco.yml` configuration. ### Require the check in branch protection To actually block merges when sign-offs are missing, enable **branch protection** on your default branch (and other protected branches as needed) and **require the DCO2 status check** to pass before merging. See GitHub’s guide on [required status checks](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) and protected branches. ### Maintainer policy: do not bypass DCO DCO2 may show a **“Set DCO to pass”** control on failed checks. **Maintainers must not use this to mark a pull request as passing** when commits are not properly signed off. Doing so undermines the policy FINOS relies on for contribution provenance. If DCO2’s override remains visible in your repository, treat it as unsupported for routine use; FINOS may remove or hide this option over time. Projects that want to hide the override UI entirely can set `allowOverrideAction: false` in `.github/dco.yml` as described in the [DCO2 README](https://github.com/cncf/dco2/blob/main/README.md) (note that this only affects the app’s button—not all ways a repository could be misconfigured). ### Getting help For DCO2 behavior, open an issue on [cncf/dco2](https://github.com/cncf/dco2). For FINOS policy questions, contact [help@finos.org](mailto:help@finos.org). --- ## EasyCLA :::caution Permissions for access to the [LFX Organization console](https://organization.lfx.linuxfoundation.org/) were designed with a little extra gating: if a new user tries to access but and is already associated with a company who had never before signed any cla, then it will ask them to [open a ticket](https://jira.linuxfoundation.org/plugins/servlet/desk/portal/4/create/143) for access. As soon as the ticket is created, feel free to send the ticket URL to help@finos.org , so we can help expediting the resolution. ::: It is important to notice that - for any given contributor covered by a Corporate CLAs - there are 2 steps necessary in order for EasyCLA to approve her/his contributions: * The CLA Manager adds an approval criteria that applies to the Contributor * The Contributor confirms her/his affiliation to the firm, by following the link provided in the first Pull Request being submitted to an EasyCLA-covered gitHub repository (see below, `Click here to be authorized`) ![EasyCLA confirm affiliation](easycla-confirm-affiliation.png) ### How to use EasyCLA #### Who signs the documents? You can sign the FINOS CLA as an individual, or your company can sign and authorize you as a contributor. The individual workflow is for people who can make CLA commitments on their own behalf (e.g., hobbyists, students, sole proprietors, etc). This workflow is fast and easy, but may not be appropriate for people who are doing work-for-hire. The corporate workflow involves more steps, but allows a company to sign one document, once, for all of their contributors. At a high level, the signature process works like this: 1. Open a PR against a repo covered by EasyCLA (including this one). 2. A bot will check whether your GitHub user is covered by a signed CLA. 3. If you're already covered you will get a green checkmark, and your contribution can be merged. 4. If you're not covered, you'll be prompted through the signature process. #### Standards projects FINOS currently hosts few Standards projects, like [FDC3](https://fdc3.finos.org) and [CDM](https://cdm.finos.org); each of them uses a "dedicated instance" EasyCLA (also known as _EasyCLA Group_), which ensures that each Standard can manage a dedicated/isolated list of approved contributors; on the contrary, all (other) FINOS non-Standards software projects are covered by the same EasyCLA Group, therefore enrolling into one project will allow contributors to also be covered across all other ones. #### Initiating the signature process against a test repo The easiest way to initiate the process is to open a PR against any covered repo, for example [proposing a small change to software-project-blueprint/EASYCLA_CHANGEME.md](https://github.com/finos/software-project-blueprint/edit/main/EASYCLA_CHANGEME.md); note that these types of PRs will be closed periodically. For more information about EasyCLA, please visit [our Community website](https://community.finos.org/docs/governance/Software-Projects/easycla). ### Sign as an individual If you are working on your own behalf and can make IP commitments about what you produce, you can sign as an individual contributor. 1. Open a PR against a repo that uses EasyCLA. 2. When blocked by the bot, follow the prompts and choose *Individual*. 3. Fill in the details and sign the DocuSign form. 4. Wait a little while for the check to re-run. That's all there is to it. ### Have your company sign for you If you are doing work for someone else (e.g., it's your job), the company might need to sign for you. The advantage here is that they can authorize other employees with a single signature. If your company has already signed the document but you're still blocked, you may just need to request your username be added to the list of authorized contributors. Once this is complete you'll just have to confirm you work for them by clicking through the process one final time. Here are the steps to have your company sign the CLA. #### If your company hasn't yet signed the agreement 1) Open a PR against a repo that uses EasyCLA. 2) When blocked by the bot, follow the prompts and choose *Corporate Contributor*. ![EasyCLA - 1 Contributor Type](https://user-images.githubusercontent.com/327285/143480686-a83b21fe-447c-471c-b6a9-4fa1e4df30de.png) 3) Choose your company from the list. If it's not there, add it. ![EasyCLA - 2 Select Organization](https://user-images.githubusercontent.com/327285/143480751-219e68ca-024d-43ae-9b17-9b949e3a1dbf.png) 4) If you're a CLA Manager, press `Yes` and login with your LFID (or create an LF Account) ![EasyCLA - 3 CLA Manager](https://user-images.githubusercontent.com/327285/143480856-3421d122-89cd-4766-a872-87c793bd0e37.png) 5) Designate someone with signing authority (generally an officer or attorney, if in doubt ask your manager) to receive the DocuSign. This person is the *CLA Manager*. ![EasyCLA - 4 Specify CLA Manager](https://user-images.githubusercontent.com/327285/143480895-ffaaca63-a636-4812-a9b7-4404939e169f.png) 6) Follow up with the CLA Manager and ask them to sign the DocuSign form; if the CLA Manager have already approved you, the Pull Request will automatically update and be marked as `Covered`. If not... 6.1. The CLA Manager can now designate other CLA Managers who are allowed to manage your company's list of authorized contributors. 6.2. The EasyCLA bot can be re-triggered by adding a comment on the Pull Request with the content `/easycla` #### When your company has finished signing the agreement 1. Once the agreement is signed, any CLA manager can [log into the EasyCLA site](https://easycla.lfx.linuxfoundation.org/#/) (choose EasyCLA v2) and either: * Add your GitHub username individually to the list of authorized contributors, or * Add your corporate email domain, which authorizes anyone who has that email in their GitHub account, or * Add a corporate GitHub Organization, where any member of the org is covered by the CLA. 2. Once this is done, you'll need to click the *Details* link in the PR (again) and click a button that acknowledges you want to be covered by the company. 3. Wait a little while for the check to re-run. At this point, your PRs will no longer be blocked by EasyCLA on any FINOS repo. #### Best practices * Ask the CLA Manager to add the corporate email domain to the list of authorized contributors, or ask them to add your corporate GitHub organization. This is much easier than adding contributors individually. ### Getting help If your company is in the system but you don't know who your CLA manager is, you can email [help@finos.org](mailto:help@finos.org). If you run into issues, you can [open a ticket in JIRA](https://jira.linuxfoundation.org/plugins/servlet/theme/portal/4/create/143). ### Adding EasyCLA to your project Here are the steps to add EasyCLA to your project. #### 1. Prepare your core contributors The single most valuable thing you can do prior to adding EasyCLA is to ensure your core contributors have already been authorized. This minimizes the potential for disruption, and can be accomplished by them simply opening a trivial PR against this repo and [following the steps](#how-to-use-easycla). (Contributors who have already signed the FINOS CLA in EasyCLA for another project do not need to do this.) You may also want to open an issue letting others know that this will be happening. #### 2. Add instructions to your project We recommend adding something like the following to your main `README` and/or `CONTRIBUTING` files, so that new contributors are not surprised. You may also consider updating your PR template to point to the instructions. Here is some suggested text you can use: ``` This repository is managed by EasyCLA. Project participants must sign the free [FINOS CLA](/docs/governance/Software-Projects/easycla) before making a contribution. You only need to do this one time, and it can be signed by individual contributors or their employers. To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a CLA from you. You can find [detailed instructions here](https://easycla.lfx.linuxfoundation.org). If you have issues, please email [help@finos.org](mailto:help@finos.org). If your company benefits from this project and you would like to provide essential financial support for the systems and people that power our community, please also consider [membership in FINOS](https://www.finos.org/membership-benefits). ``` #### 3. Request that EasyCLA be enabled When the above steps are complete, please reach out to [help@finos.org](mailto:help@finos.org) and EasyCLA will be enabled for your repos. --- ## License Categories For additional background on license categories in FINOS and related resources, see [OSLC licenses](https://osr.finos.org/docs/osr-resources/oslc-licenses) in the FINOS Open Source Readiness documentation. ### Category A #### Public Domain dedications The concept of "public domain" is a little complicated, as not every jurisdiction recognises the concept, so it's good to raise the issue to help@finos.org when it shows up. As general guidance, if the author of the library is American, the component is not a major one, and there is no public trace of issues related to the licensing of this component, there should not be problems bundling it in a FINOS (project) release. Code licensed under the following licenses (and public domain dedications) may be included in Foundation contributions. If the license requires attribution or other notices, these should be included in the project's NOTICE file. #### Common Category A Licenses - [Apache License v. 1.1 (Apache-1.1)](http://apache.org/licenses/LICENSE-1.1) - [Apache License v. 2.0 (Apache-2.0)](http://apache.org/licenses/LICENSE-2.0) - [BSD Zero Clause (0BSD)](https://spdx.org/licenses/0BSD.html) - [BSD 2-clause (BSD-2-Clause)](http://opensource.org/licenses/bsd-license.php) - [BSD 3-clause (BSD-3-Clause)](http://opensource.org/licenses/BSD-3-Clause) , or `New BSD License`, or `Modified BSD License` - [Eclipse Distribution License v. 1.0 (?)](http://www.eclipse.org/org/documents/edl-v10.php) - [ISC](https://opensource.org/licenses/ISC) - [Microsoft Public License (Ms-PL)](http://www.opensource.org/licenses/ms-pl.html) - [MIT](http://opensource.org/licenses/mit-license.php) - [PHP License v. 3.01 (PHP-3.01)](http://www.php.net/license/3_01.txt) - [PostgreSQL License (PostgreSQL)](http://opensource.org/licenses/postgresql) - [Python Software Foundation License v. 2.0 (Python-2.0)](http://www.opensource.org/licenses/PythonSoftFoundation.php) - [Unlicense](https://unlicense.org/) - [X11](https://spdx.org/licenses/X11.html) - [zlib](https://spdx.org/licenses/Zlib.html) - [zlib/libpng (zlib-acknowledgement)](http://opensource.org/licenses/zlib-license.php) #### Other Category A Licenses - ACE license (DOC) - Adobe Postscript AFM License (APAFML) - Autoconf configuration file license v. 2.0 (GPL-2.0-with-autoconf-exception) - Autoconf configuration file license v. 3.0 (GPL-3.0-with-autoconf-exception) - Bouncy Castle License (MIT) - Boost Software License Version v. 1.0 (BSL-1.0) - CERN Colt package license - Creative Commons Copyright-Only Dedication - DejaVu Fonts (Bitstream Vera/Arev licenses) - DOM4J License - Plexus - ICU License (ICU) - MX4J License (apache-1.1) OOXML XSD ECMA License Open Services Oriented Architecture Collaboration documentation license - UK Open Government License (This license allows the licensor to provide a custom attribution notice. If one is provided, include in the NOTICE. If one is not provided, include `Contains public sector information licensed under the Open Government Licence v3.0.` in the `NOTICE`.) 0 Unicode, Inc. License Agreement - Data Files and Software (Unicode-DFS-2017) - University of Illinois/NCSA Open Source License (NCSA) - Zope Public License v. 2.0 (ZPL-2.0) - W3C Software Notice and License (W3C) - Do What the F*** You Want To Public License (WTFPL) - X.Net (Xnet) ### Category B Third-party code licensed under the following licenses may be included in Foundation projects. However, because these licenses contain certain restrictions on downstream users (such as a reciprocal licensing requirement), a notice must be included in the project's CONTRIBUTING file if the third-party code appears directly in the project's repository. This is to ensure that contributors are aware when their modifications may be subject to restrictions other than those in the Apache License. - CC0-1.0 ("no material conditions at all" licenses, so they can typically be incorporated into projects under any other common open source license. But explicitly excludes a patent license, not suitable for outbound licenses) (CC0-1.0) - Common Development and Distribution License (CDDL) v. 1.0 (CDDL-1.0) - CDDL v. 1.1 (CDDL-1.1) - Common Public License (CPL) v. 1.0 (CPL-1.0) - Eclipse Public License (EPL) v. 1.0 (EPL-1.0) - Erlang Public License v. 1.1 (ErlPL-1.1) - IBM Public License (IPL) v. 1.0 (IPL-1.0) - IPA Font License Agreement v. 1.0 (IPA) - Mozilla Public License (MPL) v. 1.0 (MPL-1.0) - MPL v. 1.1 (MPL-1.1) - MPL v. 2.0 (MPL-2.0) - Ruby License - Includes the older version when GPLv2 was a listed alternative Ruby 1.9.2 license. (Ruby) - SIL Open Font License v. 1.1 (OFL-1.1) - Sun Public License (SPL) v. 1.0 (SPL-1.0) - Ubuntu Font License Version v. 1.0 - UnRAR License - Only for unarchiving ### Category X Category X dependencies are excluded either because their licenses would not permit the Foundation project to be licensed under the Apache License, or because they contain other problematic terms. Category X licenses include any proprietary license or EULA, as well as many free and open source software licenses with reciprocal licensing requirements and other restrictions. Dependencies that are licensed with a Category X license cannot be used in a Foundation project. - Academic Free License v. 3.0 (AFL-3.0) - Affero GPL (AGPL) v. 1 (AGPL-1.0) - AGPL v. 2 (AGPL-2.0) - AGPL v. 3 (AGPL-3.0) - Amazon Software License (ASL) - Apple Public Source License (all versions) (APSL-1.0, APSL-1.1, APSL-1.2, APSL-2.0) - Oracle Binary Code License (BCL) - Code Project Open License (CPOL) v. 1.02 (CPOL-1.02) - BSD 4-Clause (BSD-4-Clause) - Creative Commons Attribution (CC By) v. 2.5 CC-BY-2.5 - CC By v. 3.0 (CC-BY-3.0) - CC By v. 4.0 (CC-BY-4.0) - Most [Creative Commons](https://creativecommons.org/licenses/) licenses (when applied to source code) - European Union Public License (EUPL) v. 1.0 (EUPL-1.0) - European Union Public License (EUPL) v. 1.1 (EUPL-1.1) - GNU General Public License (GPL) v. 1 (GPL-1.0) - GPL v. 2 (GPL-2.0) - GPL v. 3 (GPL-3.0) - GNU Lesser GPL (LGPL) v. 2.1 (LGPL-2.1) - LGPL v. 3 (LGPL-3.0) - Honest Public License - JSON License (JSON) - Microsoft Limited Public License (Ms-LPL) - Netscape Public License (NPL) 1.0 (NPL-1.0) - NPL 1.1 (NPL-1.1) - Open Software License v. 3.0 (OSL-3.0) - Q Public License (QPL) 1.0 (QPL-1.0) - Sleepycat License (Sleepycat) --- ## FINOS Security Vulnerabilities Responsible Disclosure Policy :::caution Currently, FINOS does not operate a bug bounty program, and does not offer rewards or compensations of any kind in exchange for submitting potential bugs, issues or vulnerabilities. ::: FINOS defines a **set of rules to manage the lifecycle of potential vulnerabilities and security incidents within FINOS projects**. Our goal is to guarantee: 1. Discretion for new and ongoing development activity around undisclosed security vulnerabilities 2. Transparency and guidance around security vulnerabilities that have been identified, patched and released as new versions It includes step-by-step guides on [how contributors can manage security vulnerabilities](#for-finos-open-source-contributors) and [how anyone can privately submit an undisclosed security vulnerability](#for-finos-open-source-consumers) to a FINOS project. ### What are Common Vulnerabilities and Exposures The **Common Vulnerabilities and Exposures** (or [CVE](https://cve.mitre.org/cve/)) is a dictionary that provides definitions for publicly disclosed cybersecurity [vulnerabilities](https://cve.mitre.org/about/terminology.html#vulnerability) and [exposures](https://cve.mitre.org/about/terminology.html#exposure), although the term is normally used to identify CVE entries; each entry is comprised of an identification number, a description, and at least one public reference, you can check [an example on the cla-bot project](https://github.com/finos/cla-bot/issues/157). Please note that the term security vulnerability also comprises undisclosed ones, as opposed to CVEs, which only refer to publicly disclosed entries. :::danger No information should be made public about the vulnerability until it is formally announced at the end of this process. Do NOT create a GitHub Issue to track the vulnerability, since that will make the issue public. Commit messages should not make ANY reference to the security nature of the commit. ::: ### Reporting a Vulnerability In order to report a vulnerability in a FINOS project, follow these steps: 1. Visit the "Security and quality" tab of the project repository, available at `github.com/finos//security`: ![Security and quality tab](security-and-quality-tab.png) 2. Carefully read the project's `SECURITY.md` policy, in case any processes override what's described on this page: ![Security Policy](security-policy.png) 3. Follow the submission steps in the project's security policy. Usually, this means clicking the "Report a vulnerability" button and filling in the [requested details](#details-to-include). 4. If the project doesn't have a SECURITY.md policy available and the "Report a vulnerability" button is not enabled, submit the vulnerability via email to a project Maintainer (ideally, the Lead Maintainer). You can find contact emails in the project's `MAINTAINERS.md` file. Also, CC the email to [security@finos.org](mailto:security@finos.org). 5. If the project doesn't provide a contact email for a maintainer, submit the report directly to [security@finos.org](mailto:security@finos.org). :::danger Do NOT make a GitHub issue or discuss the vulnerability through public channels. ::: #### Details to include When reporting a vulnerability, it's very helpful to provide as many details as possible, including: - **Impact:** _What kind of vulnerability is it? Who is impacted?_ - **Patches:** _Has the problem been patched? What versions should users upgrade to?_ - **Workarounds:** _Is there a way for users to fix or remediate the vulnerability without upgrading?_ - **References:** _Are there any links users can visit to find out more?_ - **Screenshots (if applicable):** _Which user flows demonstrate the problem?_ #### Vulnerability remediation process 1. The project's team members work privately with the reporter to resolve the vulnerability. 2. The affected FINOS project releases a new version including the fix. 3. The vulnerability is publicly announced. For more details, see how maintainers [Manage new vulnerabilities](#managing-new-vulnerabilities) and how you can contribute to patching the issue. #### Browse security vulnerabilities for a project Published security vulnerabilities are available in the "Security and quality" tab at the repository's main page, accessible via `github.com/finos//security`. #### Information sharing If you would like to share vulnerability information with domain experts (e.g. co-workers), you must first ask the project's Security Team (maintainers, etc.) for permission. It should be made clear that the information is not for public disclosure and that [security@finos.org](mailto:security@finos.org) or the Lead Maintainer must be kept in the loop on any communication regarding the vulnerability. ### FINOS Projects Security Posture and Maintainer Obligations #### Setting up responsible disclosure To start leveraging GitHub's native disclosure and remediation process, you must add a `SECURITY.md` file describing the disclosure process. This is a sample `SECURITY.md` file that you may edit as appropriate and add to your project; just replace `PROJECT_URL` with the actual GitHub URL: ```markdown # Security Policy FINOS projects support responsible disclosure of security vulnerabilities and adheres to the [FINOS Security Vulnerabilities Responsible Disclosure Policy](https://community.finos.org/docs/governance/Software-Projects/cve-responsible-disclosure). If you find something you believe to be a security issue, we encourage and appreciate your report. Please report the issue privately to the [project maintainers]({PROJECT_URL}/blob/main/MAINTAINERS.md) using one of the following methods: ## Reporting a Vulnerability - **GitHub Security Reports:** In order for the vulnerability reports to reach maintainers as soon as possible, the preferred way is to use the ["Report a vulnerability"]({PROJECT_URL}/security) button under our "Security and quality" tab. This creates a private communication channel between you and the maintainers. - **Email:** If you are unable to or have strong reasons not to use the GitHub Security vulnerability reporting feature, please email the maintainers directly and CC: [security@finos.org](mailto:security@finos.org) with a description of the vulnerability, along with relevant details (Impact, Patches, Workarounds, References and Screenshots). ## Vulnerability Process 1. **Report the vulnerability privately** using one of the methods above. Do not create a public GitHub Issue or make any public reference to the vulnerability. 2. The project team will acknowledge receipt of your report and triage the issue. If a vulnerability is confirmed, the team will work with you to investigate and resolve it. *(Note: Maintainers must review the escalation requirements below during triage).* 3. Once a fix is available, a release will be made and the vulnerability will be publicly disclosed in accordance with the [FINOS policy](https://community.finos.org/docs/governance/Software-Projects/cve-responsible-disclosure). ## CRA Escalation (For Maintainers) This project is supported under the Linux Foundation CRA stewardship framework, as described at [https://www.linuxfoundation.org/security](https://www.linuxfoundation.org/security). Security vulnerabilities should be reported through the mechanisms described below, which we will coordinate with our CRA steward. For actively exploited vulnerabilities and severe incidents that may require CRA escalation, please use the project’s emergency security reporting mechanisms as appropriate. **Project maintainers MUST escalate** the issue to the LF steward at [steward@linuxfoundation.org](mailto:steward@linuxfoundation.org) if the project experiences either of the following: * **Actively exploited vulnerabilities:** a security vulnerability where the project has reliable evidence that a malicious actor has exploited it. * **Severe incident:** a security compromise of the project’s own IT infrastructure. Ordinary vulnerabilities with no evidence of exploitation are not CRA escalation events. Escalate those that are actively exploited. ``` Once a `SECURITY.md` file is added, you must enable private vulnerability reporting in your repository by going to **Settings** > **Advanced Security** > **Private Vunlerability Reporting** and clicking on "Enable": ![Private Vulnerability Reporting](private-vulnerability-reporting.png) If you don't have access to this menu, email [security@finos.org](mailto:security@finos.org) to request private vulnerability reporting to be activated. #### CRA escalation responsibilities FINOS projects are supported under the Linux Foundation [CRA stewardship framework](https://www.linuxfoundation.org/security). Maintainers handle ordinary vulnerability reports through the processes on this page and with [security@finos.org](mailto:security@finos.org). Certain events require escalation to the LF CRA steward. **Project maintainers MUST escalate** the issue to the LF steward at [steward@linuxfoundation.org](mailto:steward@linuxfoundation.org), and CC [security@finos.org](mailto:security@finos.org), if the project experiences either of the following: * **Actively exploited vulnerabilities:** a security vulnerability where the project has reliable evidence that a malicious actor has exploited it. * **Severe incident:** a security compromise of the project's own IT infrastructure. Ordinary vulnerabilities with no evidence of exploitation are not CRA escalation events. Escalate only those that are actively exploited, or that involve a severe incident as defined above. Maintainers must review these criteria during triage of every vulnerability report. Projects MUST document CRA escalation guidance in their `SECURITY.md` file (see the [sample above](#setting-up-responsible-disclosure)). #### Collecting project CVE list Since all CVE entries are labeled as security vulnerability, it is possible to use GitHub Issues UI to browse them. Alternatively, check the Advisories tab under the "Security and quality" tab of the project repository, also accessible at `github.com/finos//security/advisories`. #### Managing new vulnerabilities A typical process for handling a new security vulnerability is as follows. Projects that wish to use other processes MAY do so, but **MUST** clearly and publicly document their process and have FINOS team review it ahead of time. ##### Accepting a new vulnerability 1. The person discovering the issue, the reporter, reports the vulnerability privately via GitHub's native disclosure process. This automatically notifies the maintainers and [security@finos.org](mailto:security@finos.org), 2. The project team sends an e-mail to the original reporter to acknowledge the report 3. The project team investigates the report and either rejects it or accepts it. During triage, maintainers **MUST** review the [CRA escalation criteria](#cra-escalation-responsibilities) and escalate to the LF steward when required. 4. Optionally, the project team can edit the report if appropriate, and fill in or amend details including the affected/patched versions, severity and [CWE weaknesses](https://cwe.mitre.org/). ##### Working on a fix The reporter and maintainer team collaborate on a fix via GitHub's native vulnerability management system. As part of the process, they must: 1. Create a temporary private fork by clicking on the "Create private fork" button in the draft advisory page 2. Clone the fork, make a branch and commit a fix to the vulnerability **without referencing the security nature of the commits** 3. Open a PR on the private fork, which will automatically show on the advisory page 4. Review, approve and merge the PR 5. Request a CVE from GitHub Once all of these have been completed, GitHub will assign a CVE and it will be officially published, and merged to the `main` branch. If no automated release tooling is available, the team must manually make a new release, and backport the fixes to previous release lines if appropriate. ##### Apply fixes to all supported versions As soon as the project team finds and implements a fix for the vulnerability, all supported versions (most likely GitHub branches) can be patched and released. We highly recommend setting up release automation (Release Drafter, automatic version bumping) to simplify the process of backporting fixes to all active release branches. See [GitProxy's release-related workflows](https://github.com/finos/git-proxy/tree/main/.github/workflows) examples you can use in your own project. Here's an [example of a detailed release policy](https://git-proxy.finos.org/docs/development/releases/) that enabled maintainers to speed up their release process and spread the load across the team. ##### Publishing First, the team must release the patched version(s). Then, the following optional actions must be done **before** the vulnerability is published (via the GitHub Advisories UI): 1. Emailing [security@finos.org](mailto:security@finos.org) about the public disclosure 2. Notifying the original reporter about the disclosure 3. Relevant documentation must be updated (though it's highly recommended to do this *within* the private fork) Note that FINOS and the original reporter are automatically notified by GitHub on any changes on the report status. The following optional actions must be done **after** the vulnerability is published: 1. Creating follow-up issues to solve bugs that are out-of-scope for the original vulnerability 2. Creating any issue that referencing the vulnerability directly (via links, name, etc.) or indirectly ### Automating security vulnerabilities scanning FINOS provides multiple tools that adapt to languages and build platforms adopted by the project's codebase, please visit the [code validation page](https://community.finos.org/docs/development-infrastructure/code-validation/intro/). --- ## Archived Stage ### Badge ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-archived.png) Foundation-hosted projects are expected to provide a clear indication to visitors that they are in an archived stage. To this end, the Foundation provides a badge that should be displayed at the top of the project's root-level `README.md` file, using the following Markdown: ``` [![FINOS - Archived](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-archived.svg)](https://community.finos.org/docs/governance/lifecycle-stages/archived) ``` See here for a list of [FINOS Archived Projects](https://landscape.finos.org/?group=undefined&view-mode=grid&project=archived). ### Definition Projects are Archived when they are no longer actively developed, for any reason. Archived projects may no longer actively address new issues, including security vulnerabilities. Their code and documentation remain available because they may still be useful, but should be used with caution due to the lack of updates. Archived projects cannot publish anything, of any kind. If an archived project intends to make publish new or updated artifacts, it must be revived first by going through the contribution process again and being reinstated as an incubating or active project. ### Objectives Archived projects have no objectives - they are simply retained as-is, in whatever state they were in at the time of archival. The FINOS team and maintainers might, however, continue to gauge community interest in reviving the project, and will actively support such activities. Projects that are no longer active, or falter for other reasons, should be marked as archived to educate consumers and other potential evaluators. It's an important maintainer duty to trigger archival when the project is no longer maintained. Projects may be moved to the Archived state from either the Incubating or Graduated states, either upon the request of the project maintainers, or upon a determination by FINOS on the basis of the project's status. ### Initiating archival Anyone can publicly trigger the archival process for a project by [requesting archival](https://github.com/finos/community/issues/new?assignees=maoo%2C+TheJuanAndOnly99&labels=&template=project_archival.yml&title=projectName+Archival+Request); if the Project Lead Maintainer agrees that archiving is the appropriate course of action, or the project team does not respond within 14 days, the [FINOS Technical Oversight Committee](https://github.com/finos/technical-oversight-committee) will formalize the archival request. The [FINOS Technical Oversight Committee](https://github.com/finos/technical-oversight-committee) is responsible for resolving any possible dispute in case of disagreement from project teams ### Archival inactivity trigger Projects that have become inactive become eligible for archiving, where "inactivity" is defined as having had no activity (released / publications, commits, PRs, mailing list traffic, documentation updates, issue updates, etc.) in the last 180 days (6 months). ### Notes for Evaluators If you're evaluating Foundation-hosted projects and see the archived badge shown above, here are some of the things you should expect should you choose to download and use the software: - The artifacts (software, standards, etc.) produced by this activity are no longer maintained. You cannot expect that any issues you raise, or contributions you make, will be triaged, let alone addressed. - The project may not have ever been released, and therefore may never have achieved significant levels of functionality or quality. - The project may not have a team any more. Some projects are archived precisely because the team disbanded and no replacements were forthcoming from the community. The Foundation encourages community members to volunteer to revive any archived project, whether they originally contributed it or not. Reviving an existing code base is preferable to creating a competing alternative of the same functionality from scratch. --- ## Forming Stage ### Badge ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-forming.png) Foundation-hosted projects are expected to provide a clear indication to visitors that they are in a forming stage. To this end, the Foundation provides a badge that should be displayed at the top of the project's root-level `README.md` file, using the following Markdown: ``` [![FINOS - Forming](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-forming.svg)](https://community.finos.org/docs/governance/lifecycle-stages/forming) ``` Forming projects are not publicly visible (yet) but if you are a [FINOS Member](https://finos.org/members) you can request to added to a specific forming project by emailing help@finos.org ### Definition Optionally, before a project is formally contributed (in either [Labs](/docs/governance/lifecycle-stages/labs) or Incubating stage), a FINOS Platinum Member might request to work privately with other prospective contributor FINOS Members to gauge viability and evaluate interest ahead of formal contribution during what's referred as "formation". Projects which successfully complete the Formation stage are expected to become fully open source within one year. ### Objectives The objectives of the Forming stage are to gauge viability and interest for a project that is not ready for full open source availability, because of effort, quality or confidentiality reasons. The ultimate goal is to build an initial community that can ensure the project is sustainable once open sourced. ### Requirements The only requirement for a project to be accepted into Forming stage is for a FINOS Platinum Member to request it. As the project undergoes formation it will be striving to achieve the Labs or Incubating requirements ahead of contribution. ### Migration out of Forming 1. [New Project contribution](/docs/governance/Software-Projects/contribution#contribution-of-a-new-FINOS-project-or-SIG) into FINOS (as Labs or Incubating) 2. Formation effort is abandoned --- ## Graduated Stage ### Badge ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-graduated.png) Foundation-hosted projects are expected to provide a clear indication to visitors that they are in a graduated stage. To this end, the Foundation provides a badge that should be displayed at the top of the project's root-level `README.md` file, using the following Markdown: ``` [![FINOS - Graduated](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-graduated.svg)](https://community.finos.org/docs/governance/lifecycle-stages/graduated) ``` See here for a list of [FINOS Graduated Projects](https://landscape.finos.org/?group=undefined&view-mode=grid&project=graduated). ### Definition Graduated represent the highest level of maturity for FINOS projects. Projects awarded the Graduated state are in **the project is now mature in terms of quality, community, sustainability**. Projects in this stage have demonstrable widespread adoption in financial services and a healthy / diverse community of contributors. They follow best practices for collaborative software development, have mature and well-documented build and release processes, are free of high-risk security vulnerabilities, and maintain thorough documentation. Virtually all Foundation-hosted projects are expected to strive towards, and ultimately attain, Graduated status. This indicates to potential consumers that the project has reached a level of maturity, both functional and non-functional, that represents a solid long term investment. ### Objectives The objectives of the Graduated lifecycle stage are to for project team to predictably execute on an ongoing roadmap of features and bug fixes informed by feedback from the project's user base, and continue growing its community of adopters and contributors in financial services. While development activities in this stage are largely established and self-sufficient, in recognition of the achievement and to sustain project adoption, in this stage projects will receive the highest level of visibility FINOS in marketing, events, community engagement platform. ### Initiating Graduation To graduate into the Graduated stage, a project must meet [Graduated Requirements](/docs/governance/lifecycle-stages/graduated/#requirements) and [Graduated ongoing maintenance requirements](/docs/governance/lifecycle-stages/graduated/#ongoing-maintenance-requirements). Any project maintainer may request Graduation by opening a [project graduation request](https://github.com/finos/community/issues/new?assignees=maoo%2C+TheJuanAndOnly99&labels=&template=project_graduation.yml&title=projectName+Graduation+request) with an information packet demonstrating that they've met the requirements for activation (see below for details). ### Requirements #### Graduated Acceptance Requirements - All Incubation maintenance requirements must be met in addition to the following: - The project has adhered to its roadmap during Incubation - The project is self-sufficient without significant support from FINOS staff - Project has made a production-ready major release, and announced it to [announce@lists.finos.org](mailto:announce@lists.finos.org). It's recommended a project deploy a `v1.0.0` or higher version, a generally accepted signal of a stable, production-ready version, before applying. - Maintainers from at least **three** different organizations, **one** of which must be a FINOS member - Actively used by at least **five** organizations, with at least **three** from financial services - **Two** or more end-user adoption stories or case studies that can be publicly shared - The project must publish and adhere to [FINOS responsible disclosure security policy](/docs/governance/Software-Projects/cve-responsible-disclosure) - Root-level README.md must contain links to accurate and up-to-date usage and maintenance documentation - Project documentation starts with a clear, unique financial services value proposition #### Ongoing Maintenance Requirements The following must remain true for _Graduated_ projects at all times. A Health Review from the TOC will be executed every six months. Project support will be offered in the event that a project is found to be out of compliance. If a project remains out of compliance for three consecutive Health Reviews, it will qualify for archival. - All feature work adheres to a public roadmap - Demonstrated progress against the Community Development Plan milestones - Demonstrated adherence to **Maturity Level 3** of the [Open Source Project Security Baseline](https://baseline.openssf.org/) - All Graduated project starting from `v1.0.0` upward using [Semantic Versioning](http://semver.org/) ("semver"), specifically must follow the below approach to provide robust expectations for consumers: - Increment `MAJOR` version when an incompatible change is made - Increment `MINOR` version when new functionality is added in a backwards-compatible manner - Increment `PATCH` version when bugs are fixed in a backwards-compatible manner - A community sustainability plan is co-maintained with [FINOS Staff](mailto:help@finos.org), including a go-to-market strategy ### Transition out of Graduation Mature projects that become no longer actively developed should transition into FINOS Archived stage by [requesting archival](https://github.com/finos/community/issues/new?assignees=maoo%2C+TheJuanAndOnly99&labels=&template=project_archival.yml&title=projectName+Archival+Request). This is an important FINOS maintainer hygiene duty. ### Notes for Consumers and Evaluators :heavy_check_mark: The Project is high quality, mature from a codebase and community dynamics perspective. :dart: The Project produces valuable releases to solve a useful business problem for our Community. If you're evaluating FINOS project and see the Graduated badge, here are some of the things you should expect should you choose to download and use the software: - The software is functional and widely adopted in financial services - The software has high quality - it has met or exceeded all of the Foundation's security and compliance requirements, and has been well tested. - The installation & upgrade experiences should be relatively smooth - binaries will be available at a minimum, and more advanced deployment options - The project is well documented. - The project is supported by an engaged project team. While open source project do not provide a formal SLA (generally provided by commercial vendors supporting the project), bugs and enhancement requests will be triaged and addressed by the team. - Backwards compatibility is a priority, and [semantic versioning](http://semver.org/) (or similar) is used to clearly communicate breaking changes. --- ## Incubating Stage ### Badge ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-incubating.png) Foundation-hosted projects are expected to provide a clear indication to visitors that they are in an incubating stage. To this end, the Foundation provides a badge that should be displayed at the top of the project's root-level `README.md` file, using the following Markdown: ``` [![FINOS - Incubating](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-incubating.svg)](https://community.finos.org/docs/governance/lifecycle-stages/incubating) ``` See here for a list of [FINOS Incubating Projects](https://landscape.finos.org/?group=undefined&view-mode=grid&project=incubating). ### Definition This stage is for projects with high potential in early growth phase in terms of their functionality, maturity and sustainability. Projects in Incubation will typically have shown demonstrable early adoption and contributions in financial services and are seeking to accelerate their growth. During incubation, projects typically evolve towards stable technical designs, develop their openly collaborative processes, and work to grow their developer community. Incubation projects must comply with a the formal checklist defined by the [Technical Oversight Committee (TOC)](https://github.com/finos/technical-oversight-committee) and, after promotion to incubation, they must also adhere to a Incubation ongoing maintenance requirements. Incubating projects are hosted under the main [FINOS org](https://github.com/finos). ### Objectives The Incubation stage continues to nurture projects in their growth phase. The objectives of incubation are to allow the project team continue to growh functionality, adoption and contribution in the open and further figure out their collaborative processes as the community of adopters and contributors grows. By providing potential consumers of the software with a clear sign that the project is still in growth phase, the project team can also focus on innovation, relatively unburdened by support requests, backwards compatibility concerns, etc. The ultimate goal for Incubation is meet or exceed the requirements for the Graduated stage, and thereby be ready for graduation, the higher stage of maturity in FINOS. To help support this, in this stage they will receive increased FINOS infrastructure, legal, and marketing support to help bolster their visibility and adoption. The Foundation encourages the thoughtful adoption of a variety of [project collaboration services](/docs/collaboration-infrastructure) and [development tools](/docs/development-infrastructure/continuous-integration/intro); our experience has been that these services greatly expedite the creation of high quality, secure and compliant open source projects. ### How to apply for Incubation To be accepted into the Incubating stage, a project must meet the requirements of the [Incubating Lifecycle Checklist](/docs/governance/lifecycle-stages/incubating#incubating-acceptance-requirements) and [Incubating ongoing maintenance requirements](/docs/governance/lifecycle-stages/incubating#incubating-ongoing-maintenance-requirements). Generally all new projects accepted in FINOS start in the [FINOS Labs](/docs/governance/lifecycle-stages/labs) stage and then apply for promotion to Incubating stage when the project matures. But if, at the time of initial contribution to FINOS, contributors believe a project (e.g. with an existing community) is more mature than a Labs project, they have an option to directly evidence compliance with Incubating requirements. Below we detail the process for each of the two scenarios. #### Apply for promotion of a FINOS Labs Project to Incubating In order for a project to become Incubating, it must be reviewed and the change formally approved by the [Technical Oversight Committee](https://github.com/finos/technical-oversight-committee). Any project maintainer may initiate this request process at any time by opening an [Incubation promotion request](https://github.com/finos/community/issues/new?assignees=maoo%2C+TheJuanAndOnly99&labels=&template=project_incubation.yml&title=ProjectName+Incubation+promotion+request) with an information packet demonstrating that they've met the requirements for Incubating. #### Contribution of a new project directly into Incubating stage If you are a FINOS Member (or you have a FINOS Member maintainer) and would like to contribute an open source or open standard project directly into Incubating stage, please follow the [new Project contribution process](/docs/governance/Software-Projects/contribution#contribution-of-a-new-FINOS-project-or-SIG) ### Requirements #### Incubating Acceptance Requirements - All [FINOS Labs](/docs/governance/lifecycle-stages/labs) acceptance and maintenance requirements must be met in addition to the following: - At least **two** maintainers from different organizations, **one** of which must be a [FINOS member](https://finos.org/members) - Active use by at least two financial services organizations - At least one detailed end-user adoption story (public or private to the TOC) - Consistent adherence to the contribution workflow described in the project’s CONTRIBUTING.md - Project implements the appropriate governance structure according to [FINOS Community Governance](/docs/governance/#community-governance) - A public roadmap or project backlog with target outcomes and timelines in or linked from the repo #### Incubating Ongoing Maintenance Requirements The following must remain true for _Incubating_ projects at all times. A Health Review from the TOC should be expected every six months. Project support will be offered in the event that a project is found to be out of compliance. If a project remains out of compliance for three consecutive Health Reviews, it will qualify for archival. - All _Incubation_ acceptance requirements and _Labs_ maintenance requirements - Public tracking of activity using GitHub Issues - A shortlist of public “Good First Issues” or “Help Wanted” remains accurate and up-to-date - All open issues and discussions are replied to with reasonable promptness - Publicly visible adherence to a project roadmap - Pre-release integration with a [FINOS-approved dependency and license scanner](/docs/development-infrastructure/code-validation/intro) - Build and release processes do not use any private or undocumented steps - Presentation once every six months at a public TOC meeting - Demonstrated adherence to **Maturity Level 2** of the [Open Source Project Security Baseline](https://baseline.openssf.org/) ### Transition out of Incubation As projects become more mature they have several options to progress: 1. Graduate into FINOS Graduated stage by [requesting graduation](https://github.com/finos/community/issues/new?template=project_graduation.yml). Mature projects may request graduation quickly. In fact there are no expectations or requirements for how long projects incubate, provided they are being actively developed. 2. Graduate to another LF foundation (if scope / audience has grown beyond finance) 3. Transition into FINOS Archived stage by [requesting archival](https://github.com/finos/community/issues/new?template=project_archival.yml) if the project is no longer actively developed. This is an important FINOS maintainer hygiene duty. ### Notes for Consumers and other Evaluators If you're evaluating Foundation-hosted open source projects and see the Incubating badge shown above, here are some of the things you should expect should you choose to download and use the software: * The software is in its early adoption phase, from a functional perspective or a quality (security, compliance, testing) perspective. * The code is under active development, so you should expect a rapid rate of changes. * The community is in growth mode, therefore it might still be reliant of a limited set of core contributors. You can evaluate project health metrics using [LFX Insights](https://insights.linuxfoundation.org/). --- ## Labs Stage ### Badge ![](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-labs.png) Foundation-hosted projects are expected to provide a clear indication to visitors that they are in the labs stage. To this end, the Foundation provides a badge that should be displayed at the top of the project's root-level `README.md` file, using the following Markdown: ``` [![FINOS - Labs](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-labs.png)](https://community.finos.org/docs/governance/lifecycle-stages/labs) ``` See here for a list of [FINOS Labs](https://github.com/finos-labs/) projects. ### Definition Projects in the FINOS Labs stage are in an experimental and exploratory phase. To clearly differentiate their early stage maturity, projects in this stage are hosted in the dedicated [FINOS Labs](https://github.com/finos-labs/) Github org, separate from the main [FINOS org](https://github.com/finos). ### Objectives The objective of the Labs labs stage is to provide a low-friction environment to allow the project team to experiment under a neutral governance in the open, and work through their concepts collaboratively within the FINOS umbrella. This stage serves the default entry stage for all new projects contributed to FINOS, allowing for quick evolution towards project-market-fit. This stage is also used to support FINOS hackathons providing an immediately open source outlet for projects built during these events. Once established, Labs projects are expected to prioritise some or all of the following activities, in approximately this order: 1. Rapid experimentation e.g. with different technical designs, deployment architectures, platforms & capabilities etc. 2. Selection and adoption of an appropriate SDLC and supporting [project infrastructure services](/docs/collaboration-infrastructure). 3. Construction of an implementation timeline or additions to the project roadmap 4. Development and testing. ### How to apply for FINOS Labs To be accepted, Labs projects must comply with formal [FINOS Labs Acceptance Requirements](/docs/governance/lifecycle-stages/labs#labs-acceptance-requirements) by the [Technical Oversight Committee (TOC)](https://github.com/finos/technical-oversight-committee) and enforced by the FINOS staff. After acceptance, they must also adhere to a short list [FINOS Labs ongoing maintainance requirements](/docs/governance/lifecycle-stages/labs#labs-ongoing-maintenance-requirements). If you are a FINOS Member (or have a FINOS member as a maintainer of your project) and would like to contribute a new open source or open standard project into Labs, please follow the [new Project contribution process](/docs/governance/Software-Projects/contribution#contribution-of-a-new-FINOS-project-or-SIG) to: 1. detail the proposal 2. evidence your compliance the [FINOS Labs Acceptance Requirements](/docs/governance/lifecycle-stages/labs#labs-acceptance-requirements) 3. commit to fulfill the [FINOS Labs ongoing maintainance requirements](/docs/governance/lifecycle-stages/labs#labs-ongoing-maintenance-requirements). If you believe your project is more mature than a Labs project, at the time of contribution you will have an option to evidence compliance with later stages and contextually request the [Technical Oversight Committee](https://github.com/finos/technical-oversight-committee) to award [Incubating](/docs/governance/lifecycle-stages/incubating) or [Graduated](/docs/governance/lifecycle-stages/graduated) stage. ### Requirements #### Labs Acceptance Requirements The following factors must be confirmed before the project can be accepted and onboarded as a FINOS Labs Project. - Project has a clear use case for the financial services industry - Next steps for development are documented in the README or a linked document - Project name and logo, if extant, comply with the [FINOS trademark requirements](/docs/governance/Software-Projects/contribution#trademark); Otherwise a new name / logo is agreed during contribution - Project's license must comply with the [FINOS IP Policy](https://community.finos.org/governance-docs/IP-policy.pdf) - The above may be brought into compliance during the contribution process before final onboarding #### Labs Ongoing Maintenance Requirements The following must remain true for projects at all times. A Health Review may be done by the FINOS TOC or Staff as often as once every six months. Project support will be offered in the event that a project is found to be out of compliance. If a project remains out of compliance for two consecutive Health Reviews, it will qualify for archival. - All _Labs_ acceptance requirements - Public FINOS GitHub repository must have development activity since the last Health Review - Completion of any action items issued to the project following a vote of the TOC - LICENSE, NOTICE and CONTRIBUTING files conform to [FINOS compliance requirements](/docs/governance/Software-Projects/contribution-compliance-requirements#license-information) - All community meetings are run according to [FINOS meeting procedures](/docs/governance/meeting-procedures) - The appropriate [FINOS Labs Badge](https://raw.githubusercontent.com/finos/contrib-toolbox/master/images/badge-labs.png) is displayed at the top of the project README - All official project websites or related assets are owned and hosted by FINOS - Use of an automated build and release pipeline when releases are made - Released artifacts must be distributed under a FINOS namespace following language-specific best practices - Demonstrated adherence to Maturity Level 1 of the [Open Source Project Security Baseline](https://baseline.openssf.org/) ### Transition out of Labs As projects become more mature they have several options to progress: 1. Transition into FINOS Incubating stage by [requesting incubation](https://github.com/finos/community/issues/new?assignees=maoo%2C+TheJuanAndOnly99&labels=&template=project_incubation.yml&title=projectName+Incubation+Request). 2. Transition into FINOS Graduated stage by [requesting graduation](https://github.com/finos/community/issues/new?assignees=maoo%2C+TheJuanAndOnly99&labels=&template=project_graduation.yml&title=projectName+Graduation+Request). 3. Graduate to another LF foundation (if scope / audience has grown beyond finance) 5. Archive ### Notes for Consumers and other Evaluators If you're evaluating Foundation-hosted open source projects and see the Labs badge shown above, here are some of the things you should expect should you choose to download and use the software: * The software is not guaranteed to be "finished", either from a functional perspective or a quality (security, compliance, testing) perspective. As a result you should expect to run into bugs and missing features. * The code is under active development, so you should expect a rapid rate of changes. * The installation & upgrade experiences may be primitive or non-existent - you may have to build the project yourself simply in order to evaluate it. * Documentation may be primitive or non-existent. * Supporting users of the software is not necessarily a priority of the project team yet, so while your feedback (bug reports, etc.) will be gratefully received, it may not be acted upon immediately. * Backwards compatibility is unlikely to be a priority, so it's likely that breaking changes will appear in various revisions of the project. You should be especially conscious of this if the project is developer-oriented (a library or SDK) - APIs likely will change repeatedly during incubation. The above list also suggests ample opportunity for contribution - documentation enhancements, for example, are a great way to contribute back to a project without necessarily having to invest a lot of time in tooling or code comprehension. --- ## Special Interest Groups Special Interest Groups provide a venue to discuss and compare notes on a common topic of interest. SIGs governance is documented [here](/docs/governance#special-interest-groups). Here's a list of special interest groups (SIGs) currently active in FINOS: | Name | Charter | Chair | Approved on | |---|---|---|---| | [Open Source Readiness](https://github.com/finos/open-source-readiness) | Be a trusted venue for our Members and Community in their open source journey and enable them to achieve the highest state of open source maturity.| Cara Delia (Red Hat) Brittany Istenes (Fannie Mae) Thomas Cooper (RBC) Peter Smulovics (Morgan Stanley) | April 21st 2021 | | [Financial Objects](https://github.com/finos/finos-fo/) | Provide a neutral forum for individuals across the financial services industry to collectively identify the need for new, open, financial objects standards as well as modifications to existing ones. Work to promote adoption of financial object definitions and models that support common industry workflows and use cases.| Ffion Acland (Goldman Sachs) Ian Sloyan (ISDA) | April 21st 2021| | [Innersource](https://github.com/finos/InnerSource/) | Create a safe space to identify and share challenges and solutions that accelerate Financial Services organizations’ efforts to implement InnerSource. | [Chairs](https://github.com/finos/InnerSource#innersource-sig-leadership) | [January 20th, 2021](/governance-docs/202101-InnerSource-SIG-Proposal-APPROVED.pdf) | | [Regulation Innovation](https://github.com/finos/open-regtech) | The Regulation Innovation SIG will be a community of people interested in creating open source solutions for regulatory and compliance issues. Creating open source solutions to regulatory compliance is particularly important because the market is currently using custom-built, one-off solutions, that are expensive, inefficient, and costly to manage and update over time. | Ian Hollowbread (ING) David Ehrich (AIR) | October 21st 2020 | | [DevOps Automation](https://github.com/finos/devops-automation) | Identify and share homegrown solutions that enable regulated enterprises to manage the engineering toolchain, from ‘admin proxies’ to ‘glue to connect multiple tools together’, whilst finding opportunities to collaborate with the FINOS Community and possibly set standards on how these challenges should be addressed. | Amol Shukla (Morgan Stanley) Robb Keayes (Nomura) | October 21st 2020 | | [Open Source Talent Acceleration](https://github.com/finos/open-source-talent-acceleration) | To provide actionable pathways for newcomers and mid-career professionals to nurture and drive continuous growth; bridge the skill gap and optimize the impact of open-source collaboration for FSIs. | [Chairs](https://github.com/finos/open-source-talent-acceleration?tab=readme-ov-file#co-chairs-2025) | In January 2022, the Board ratified this group operating as a SIG, after one year running as a Board committee | January 2022 | | [Zenith](https://github.com/finos/zenith) | To explore and promote the adoption of new and innovative technologies in the financial services industry. | Peter Smulovics (Morgan Stanley) Keith O'Donell (Feynic) Patrick Downing (Morgan Stanley) | April 26th 2023 | | [AI Readiness](https://github.com/finos/ai-readiness) | Our goal is to mutually develop a governance framework that manages the on-boarding, development of, and running AI-based solutions within financial services organisations - allowing us all to unlock the potential of this disruptive technology in a safe, trustworthy and compliant way. | Colin Eberhardt (Scott Logic) Ian Micallef (Citi) | January 30th 2024 | | ![badge-labs](https://user-images.githubusercontent.com/327285/230928932-7c75f8ed-e57b-41db-9fb7-a292a13a1e58.svg) [Distinguished Engineer Community](https://github.com/finos-labs/distinguished-engineer-community) | To build a community of Engineering leaders who can influence digital technology to have a positive impact on society. | Chair: Mark Brotherwood (Davies Group) Co-Chair: Peter Thomas, DB | The SIG was approved on May 13th 2025 to begin operating in [finos-labs](https://github.com/finos-labs/) | ### Want to propose a new SIG? If you are FINOS member and you'd like to propose a new SIG for Board approval, [just raise an issue](https://github.com/finos/community/issues/new?assignees=TheJuanAndOnly99%2C+maoo&labels=contribution&template=special_interest_group_contribution.yml&title=Special+Interest+Group+Contribution+and+Onboarding) and the FINOS team will work with you to bring the proposal to the Board if relevant. --- ## Leveraging FINOS to Build Flourishing Projects and SIGs **Leveraging FINOS to Build Flourishing Projects and SIGs** is a presentation given to FINOS Project and SIG leads that demonstrates the FINOS 2022 Community Strategy. https://user-images.githubusercontent.com/6029572/159551146-8d8ea8e4-7c2b-4318-a46f-3c0a20c0b788.mp4 ### Download as a PDF The original presentation can be [downloaded as a PDF](https://github.com/finos/community/blob/master/website/static/growing-your-project-community/finos-2022-community-strategy-public.pdf). ### Markdown Content 1. [FINOS Community 2022 Strategic Overview](finos-community-2022-strategic-overview.md) 2. [Communicate WHY and HOW the FINOS Community should contribute](communicate-why-and-how.md) 3. [Provide an amazing engineering experience for first time contributors](provide-an-amazing-engineering-experience.md) 4. [Coordinate work through GitHub Issues, Discussions and FINOS Slack](coordinate-work.md) 5. [Create an Open Profile to Benefit Maintainers and Contributors](create-an-open-profile.md) 6. [Measure FINOS Project and SIG Success with LFX Insights](measure-finos-project-and-sig-success.md) 7. [Work with FINOS to Recognise Community Achievements](recognise-community-achievements.md) 8. [Ensure FINOS Project Security with LF Security Training and OpenSSF](ensure-finos-project-security.md) --- ## Communicate WHY and HOW the FINOS Community should contribute https://user-images.githubusercontent.com/6029572/159290369-2798a41f-8b1f-4c5f-9639-102bed68a24d.mp4 Successful open source Projects and SIGs clearly communicate their purpose and tell people why and how they should contribute and consume. Look at [Morphir](https://github.com/finos/morphir), [ReactJS](https://github.com/facebook/react), [Svelte](https://github.com/sveltejs/svelte) for great examples. ### Update or Add Content to FINOS Project and SIG README.md and CONTRIBUTING.md - Articulate your FINOS Project and SIG purpose in your README.md - Invite the team to review and feedback to make sure it makes sense. - Update your CONTRIBUTING.md to include the following ... - How to get involved - Provide a Getting Started guide - Invite contributors to look through **open GitHub Issues**, **“Help Wanted”** and **“Good First Issues”** - Invite contributors to **open pull requests** and **fix bugs** and **contribute features** - Remember to invite the FINOS Community to open issues if bugs are found! **Remember to update FINOS Project and SIG microsites to reflect consistent content!** ![](https://github.com/finos/community/blob/master/website/static/growing-your-project-community/why-how.png?raw=true) [← Back to Index](README.md) --- ## Coordinate work through GitHub Issues, Discussions and FINOS Slack https://user-images.githubusercontent.com/6029572/159291495-3170c159-04a6-4b75-a122-acb7b0d88cca.mp4 ### Take full advantage of GitHub Issues for work allocation - Use GitHub Issues to create a backlog of well described work e.g. ([Legend](https://github.com/finos/legend/issues)). - Allocate work to individuals so the team knows what they’re doing e.g ([FDC3](https://github.com/finos/fdc3/issues)). - Invite external contribution with “Help Wanted” and “Good First Issue” labels. ### GitHub Discussions for Async Communication - Use GitHub Discussions for new ideas and topics of interest e.g. ([CFI](https://github.com/finos/compliant-financial-infrastructure/discussions)). - Enables the threaded conversations across the Project and SIG communities. - An awesome way to communicate when Slack is restricted. ### Join FINOS Slack to keep in contact with your FINOS Project and SIG - Slack enables real time and asynchronous team communication. - Slack channels can notify the latest status of your Project or SIG repository. - An awesome way to accelerate your team communication. - Find out [how to join the FINOS Slack](https://www.finos.org/blog/finos-announces-new-community-slack). ### Essential Learning Resource for FINOS Projects and SIGs - Learn about GitHub Issues and Discussions with this awesome [GitHub 101 Training](https://docs.github.com/en/get-started/quickstart/hello-world). - Take the [Free Linux Foundation Open Source Best Practices Training](https://training.linuxfoundation.org/full-catalog/?_sft_topic_area=open-source-best-practice). [← Back to Index](README.md) --- ## Create an Open Profile to Benefit Maintainers and Contributors https://user-images.githubusercontent.com/6029572/159292145-3a19fdea-37c6-4a9e-bad9-d00983e372d7.mp4 ### Maintainers - Identify key contributors based on their FINOS Project and SIG contributions. ### Contributors - Keeps your OSS resume up-to-date across Linux Foundation Projects and SIGs. - Centralised login experience across Linux Foundation events, training and products. - Highlights your FINOS and Linux Foundation community impact. ### Next Steps - Create an Open Profile account on the LFX Homepage - https://lfx.linuxfoundation.org/ - Register your LinkedIn account to auto populate your FINOS contribution history! ![](https://github.com/finos/community/blob/master/website/static/growing-your-project-community/open-profile.png?raw=true) [← Back to Index](README.md) --- ## Ensure FINOS Project Security with LF Security Training and OpenSSF https://user-images.githubusercontent.com/6029572/159292641-7a6d0b3a-0de7-4e7e-9699-41d2990a9f58.mp4 FINOS with the **Open Source Security Foundation** primary objective is protecting the open source supply chain against malicious attacks and bad actors. This makes security everyone’s OSS priority. ### Follow OpenSSF Best Practices and get your OpenSSF Badge Register for the [OpenSSF Best Practices Badge](https://github.com/coreinfrastructure/best-practices-badge) to demonstrate your project security directly on your README whilst guiding your team through industry best practices to secure your Project and SIG. ### Take the Free Linux Foundation Secure Software Development Training Every FINOS maintainer and contributor should take the [Free LF EdX courses on secure software development](https://openssf.org/training/courses/) to ensure security first thinking. All Linux Foundation courses appear on your Open Profile. ![](https://github.com/finos/community/blob/master/website/static/growing-your-project-community/security.png?raw=true) [← Back to Index](README.md) --- ## FINOS Community 2022 Strategic Overview There are many communities surrounding FINOS, with Projects and SIGs attracting people from lots of different backgrounds, that we should all work to Recruit, Reward and Retain in 2022. https://user-images.githubusercontent.com/6029572/159919438-c794221e-72b5-4d50-b71f-9285c9ca205b.mp4 The FINOS Community Strategy centers around the FINOS Community On Ramp that implements an approach for directly educating, growing and rewarding FINOS OSS contributors. ![](https://github.com/finos/community/blob/master/website/static/growing-your-project-community/finos-on-ramp.png?raw=true) ### FINOS Community On Ramp Steps Lets break the FINOS Community On Ramp down into some specifics ... https://user-images.githubusercontent.com/6029572/159919596-400834c9-7915-42dc-a8bd-35d0cf1ce401.mp4 1. FINOS contributors should know why they should contribute to FINOS Projects and SIGs. 2. Projects and tools should be installed locally in 10 mins or less. Think engineering experience. 3. FINOS Projects and SIGs should publish and educate how contributors can get involved. 4. Backlog items tagged Good First Issues and ideally assigned to individuals and communicated via Calls / GitHub / FINOS Slack. 5. FINOS Project and SIG communities should work to resolve blockers & answer questions fast. 6. Contributions, achievements and releases should be publicly celebrated. [← Back to Index](README.md) --- ## Measure FINOS Project and SIG Success with LFX Insights https://user-images.githubusercontent.com/6029572/159293060-76fd0411-7846-4ed5-9b8a-d27a03468212.mp4 ### Data-driven reporting enables you to make informed decisions. - Track FINOS Project and SIG trends with rich engagement driven reports. - Data driven project health helps identify best practices within your teams. - Drill down into performance metrics across the open source development lifecycle. - Analyse technical trends, team performance, ecosystem and community statistics. ![](https://github.com/finos/community/blob/master/website/static/growing-your-project-community/insights.png?raw=true) ### Next Steps - Use https://metrics.finos.org/ to find your FINOS Project and SIG filtered Insights. - Review with your teams to determine your FINOS Project and SIG growth metrics. - Include metrics review in team meetings / sprint reviews to help influence direction and decisions. - Work with FINOS to grow your Projects and SIGs and celebrate your success! [← Back to Index](README.md) --- ## Provide an amazing engineering experience for first time contributors https://user-images.githubusercontent.com/6029572/159293646-34b06315-1774-4cce-805a-45a2e090ac24.mp4 Sometimes having documentation isn’t enough for attracting contributors and scaling your projects. Engineering Experience is about leveraging technology to demonstrate impact in under 10 mins. ### Explore cloud and open source projects / platforms for mechanisms of fast deployment - JavaScript libraries should leverage NPM for fast deployment and usage. - JavaScript frameworks should leverage NPX for quick deployment and configuration. - FINOS SIGs should utilize markdown and microsites for publishing and consuming materials fast. - Docker and containers should be leveraged for deploying complex software systems. - Cloud services should be leveraged as an alternative to self hosting systems. - Kubernetes should be leveraged for deploying hybrid cloud and locally run systems. - Juju and Charms can be used for Kubernetes deployment and day two system orchestration. ![](https://github.com/finos/community/blob/master/website/static/growing-your-project-community/devops.png?raw=true) **Why invest in an awesome engineering experience?** Easy and speed of deployment enables innovation, playful experiments and lowers the barrier of entry to open source consumption and contribution. When you deploy fast, you can run hackathons! [← Back to Index](README.md) --- ## Work with FINOS to Recognise Community Achievements The diagram below illustrates the FINOS Recognition and Reward mechanism. ![](https://github.com/finos/community/blob/master/website/static/growing-your-project-community/recognise-community-achievements.png?raw=true) [← Back to Index](README.md) --- ## FINOS Community Meetups The following are details of all FINOS and FINOS Member / Partner meetups open to the FINOS and wider open source community to join. Please reach out to help@finos.org if you'd like to organize or present at a FINOS meetup. ### Presenting at a FINOS meetup Organiser details are also provided for FINOS projects and special interest groups wanting to join, present or demo to any FINOS meetup community. ### FINOS Open Source UK Meetups ![alt text](../../images/open-source-london.png "Open Source UK Meetups") #### Meetup Organisers - Claire Cocks, Business Development Campaign Manager, Scott Logic - ccocks@scottlogic.com - Paul Dykes, Content and Channel Manager, Scott Logic - PDykes@scottlogic.com #### UK Meetups | Meetup Name | Description | Where to find us | | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- | | Open Source London | Organised in partnership by FINOS and Scott Logic, the London Open Source Meetup aims to expand contributions to and consumption of open source technologies, while growing a healthy engineering community in the financial services industry. | https://www.meetup.com/open-source-london/ | | Open Source Edinburgh | Organised in partnership by FINOS and Scott Logic, the Edinburgh Open Source Fintech Meetup aims to expand contributions to and consumption of open source technologies, while growing a healthy engineering community in the financial services industry. | https://www.meetup.com/open-source-edinburgh/ | | Open Source Bristol | Organised in partnership by FINOS and Scott Logic, the Bristol Open Source Fintech Meetup aims to expand contributions to and consumption of open source technologies, while growing a healthy engineering community in the financial services industry. | https://www.meetup.com/open-source-bristol/ | | Open Source Leeds | Organised in partnership by FINOS and Scott Logic, the Leeds Open Source Meetup aims to expand contributions to and consumption of open source technologies, while growing a healthy engineering community in the financial services industry. | https://www.meetup.com/open-source-leeds/ | ### FDC3 Sweden Meetups ![alt text](../../images/fdc3-sweden.png "FDC3 Sweden") #### Meetup Organisers - Aleksandar Marinkovic - alex.marinkovic@linux.com #### Sweden Meetups | Meetup Name | Description | Where to find us | | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------- | | FDC3 Sweden | Organized in partnership with FINOS, the FDC3 Sweden Meetup aims to expand contributions to and consumption of FDC3 open standards for financial desktop technologies while growing a healthy engineering community in the financial services industry. | https://www.meetup.com/fdc3-sweden/ | --- ## Consume ### Ready to consume? The first step in engaging with any open source initiative is typically to consume the work produced so far, and the teams behind that work. If you've already identified [an open source component or open standard in our Landscape](https://landscape.finos.org) that you would like to use or build on, please do so! ### Discover interesting projects The [FINOS Landscape](https://landscape.finos.org) makes it easy to discover FINOS Special Interest Groups, software projects, and standards projects. You can also browse the [FINOS GitHub organization](https://github.com/finos) and [FINOS GitLab organization](https://gitlab.com/finosfoundation/) directly. If you need help finding something, ask via [mailing lists](https://community.finos.org/docs/journey/engage#mailing-lists), the [FINOS Community Slack channel](https://finos-lf.slack.com/messages/finos-community/), or [help@finos.org](mailto:help@finos.org). ### Where are FINOS releases? How a particular project asset is consumed will vary from project to project. [Software projects](/docs/governance/#open-source-software-projects) publish releases to Open Source repositories ([Maven Central](https://central.sonatype.com/search?q=org.finos&smo=true), [NPM](https://www.npmjs.com/search?q=finos), [NuGet](https://www.nuget.org/packages?q=finos), [DockerHub](https://hub.docker.com/u/finos) and [Pypi](https://pypi.org/user/finos/)) while binary utilities may be also made available as GitHub/Gitlab downloads on the project's repository. The best way to determine how to consume a project's releases is to refer to that project's documentation. All of the above applies to [open standards projects](/docs/governance/#open-standard-projects), such as [FDC3](https://fdc3.finos.org), as well. ### Evaluating maturity of our projects We encourage you to thoughtfully assess not only the **value** and **fit for purpose**, but also the **maturity** of both the technology and the team that produced a particular code asset. Evaluating the project's momentum and longevity will help you assess the level of technical risk that you may be taking on when leveraging it. FINOS provides tools to help the community in these assessments, particularly: - The [Project Lifecycle](/docs/governance/project-lifecycle) which provides a single overall measure of the maturity of our projects - The [Metrics Dashboard](https://metrics.finos.org) which provides transparent analytics on the activity of each of our Projects and SIGs Once you've identified suitable components we encourage you to consume them in your own software development efforts! ### FINOS ensures Security and IP Compliance of our projects As an open source community in a regulated industry, we are well aware of the strong enterprise requirements of our project consumers. That is why we publish clear [contribution requirements](https://community.finos.org/docs/governance/Software-Projects/contribution-compliance-requirements) (including DCO or CLA as appropriate), [EasyCLA](https://community.finos.org/docs/governance/Software-Projects/easycla) where projects use CLA, and increasingly mandatory [security scanning](https://community.finos.org/docs/development-infrastructure/code-validation/whitesource), backed [by a responsible disclosure policy](https://community.finos.org/docs/governance/Software-Projects/cve-responsible-disclosure). ### Ready to contribute back? As you consume FINOS projects, you may be willing to take an active role in the development by [Engaging](/docs/journey/engage) with or [Contributing](https://community.finos.org/docs/journey/participate/) to that project. As an open community, we encourage you to participate in the Projects or Special Interest Groups (SIGs) whose work you consume! ### Does your firm need help contribute? If you need help consuming open source code, the [FINOS Open Source Readiness (OSR) Initiative](https://www.finos.org/open-source-readiness) supports financial services organizations in their open source maturity journey. Get in touch and start realizing the benefits of open source code and collaboration today. The [Knowledge Base](https://www.finos.org/knowledge-base) is another useful starting point. --- ## Engage If you have already [learned](https://community.finos.org/docs/journey/learn) how FINOS works and started [using FINOS projects](https://community.finos.org/docs/journey/consume), this page shows how to take the next step: engage with the community and participate in activities across our [landscape](https://landscape.finos.org). ### Code of Conduct Violations Before we start, please know that all in-person and online interactions must happen within our [Community Code of Conduct page](https://www.finos.org/code-of-conduct). Instructions on reporting Code of Conduct violations are also included in that page. ### Engage & Amplify our message As an individual you can play a huge part in amplifying our open-source message by following us, engaging / resharing, and sending us questions / feedback on [X](https://twitter.com/finosfoundation) or [LinkedIn](https://www.linkedin.com/company/finosfoundation/). ### Meet the Community! Why not join a Project or a SIG online Meeting? Browse the [FINOS Community Calendar](https://www.finos.org/calendar) and know all of our project or SIG meetings are open to anyone and free to attend. Ready to meet the Community at large, online or in person? Take a look at our [recurring meetups schedule](/docs/growing-your-project-community/meetups) and our [Events](https://www.finos.org/hosted-events), including our flagship event the [Open Source in Finance Forum](https://events.linuxfoundation.org/open-source-finance-forum/), the global event solely dedicated to open source in financial services. ### Mailing Lists FINOS mailing lists are a key channel for community activity. Below is a list of commonly used foundation-wide and project-specific mailing lists. Most lists are hosted on Google Groups (**Google login required** for web access). > In order to subscribe to any of the FINOS-wide or project-specific mailing lists, you can either send an email to `+subscribe@finos.org` or > visit the web archive link on Google Group. Please note that the latter option may be blocked by some financial services organizations. For example, to > subscribe to community@finos.org, email [community+subscribe@finos.org](mailto:community+subscribe@finos.org). Please note that membership in some lists is restricted, and requests to subscribe to those lists may only be accepted if membership requirements are met. In order to manage spam, all Foundation mailing lists that allow posting by the general public are moderated, which can result in slight delays in delivery. If you sent an email to one of these lists and your message was not acknowledged, or you do not see your message in the web archive, please email [help@finos.org](mailto:help@finos.org). #### Foundation-wide Lists - [general@finos.org](mailto:general+subscribe@finos.org) - General entry point to the Community, ask questions, propose an idea or ask feedback to the Community at large. Includes all the Program general lists and FINOS staff. ([web archive](https://groups.google.com/a/finos.org/g/general)) - [announce@finos.org](mailto:announce+subscribe@finos.org) - Announcements and new program proposals. ([web archive](https://groups.google.com/a/finos.org/g/announce)) - [members@finos.org](mailto:members+subscribe@finos.org) - Foundation Membership discussions and announcements (available to all employees of Foundation member organisations). ([web archive](https://groups.google.com/a/finos.org/g/members)) #### Project & SIG specific Lists Most projects maintain mailing lists that anyone can post to. The mailing list reaches all participants in that project. They are a good venue for scope, functional, and technical questions about the project as well as expressing an interest in participating. You can self subscribe to any public FINOS mailing list by sending an email to the list with a `+subscribe` added after the name of the list, like so fdc3+subscribe@finos.org. You can also email help@finos.org and request to be added directly. Below is a list of all FINOS Project & SIG mailing lists: - 5spot — [5spot@lists.finos.org](mailto:5spot+subscribe@lists.finos.org) - AI Evaluation Framework — [ai-evals-framework@lists.finos.org](mailto:ai-evals-framework+subscribe@lists.finos.org) - AI Governance Framework — [ai-governance-framework@lists.finos.org](mailto:ai-governance-framework+subscribe@lists.finos.org) - AI Readiness SIG — [ai-readiness@finos.org](mailto:ai-readiness+subscribe@finos.org) - AI Reference Architecture Library — [ai-reference-architecture-library@lists.finos.org](mailto:ai-reference-architecture-library+subscribe@lists.finos.org) - Applied GenAI — [applied-genai@lists.finos.org](mailto:applied-genai+subscribe@lists.finos.org) - CALM — [calm@lists.finos.org](mailto:calm+subscribe@lists.finos.org) - Common Cloud Controls — [ccc-participants@lists.finos.org](mailto:ccc-participants+subscribe@lists.finos.org) - Common Domain Model — [cdm@lists.finos.org](mailto:cdm+subscribe@lists.finos.org) - DevOps Automation SIG — [devops-automation@finos.org](mailto:devops-automation+subscribe@finos.org) - Distinguished Engineer Community — [distinguished-engineer-community@lists.finos.org](mailto:distinguished-engineer-community+subscribe@lists.finos.org) - FDC3 Sail — [fdc3-sail@lists.finos.org](mailto:fdc3-sail+subscribe@lists.finos.org) - FDC3 Standard — [fdc3@finos.org](mailto:fdc3+subscribe@finos.org) - Financial Objects SIG — [fo@finos.org](mailto:fo+subscribe@finos.org) - Fluxnova — [fluxnova@lists.finos.org](mailto:fluxnova+subscribe@lists.finos.org) - Git Proxy — [git-proxy@lists.finos.org](mailto:git-proxy+subscribe@lists.finos.org) - Innersource SIG — [innersource@finos.org](mailto:innersource+subscribe@finos.org) - KDB — [data-tech-kdb@finos.org](mailto:data-tech-kdb+subscribe@finos.org) - Konspekt — [konspekt-general@lists.finos.org](mailto:konspekt-general+subscribe@lists.finos.org) - Legend Project — [legend@finos.org](mailto:legend+subscribe@finos.org) - Morphir — [morphir@finos.org](mailto:morphir+subscribe@finos.org) - Open Developer Platform — [odp@finos.org](mailto:odp+subscribe@finos.org) - Open Financial LLM — [open-financial-llm@lists.finos.org](mailto:open-financial-llm+subscribe@lists.finos.org) - Open Resource Broker — [open-resource-broker@lists.finos.org](mailto:open-resource-broker+subscribe@lists.finos.org) - OpenGRIS — [opengris@lists.finos.org](mailto:opengris+subscribe@lists.finos.org) - Open Regtech SIG — [open-regtech-sig@finos.org](mailto:open-regtech-sig+subscribe@finos.org) - Open Source Readiness SIG — [osr@finos.org](mailto:osr+subscribe@finos.org) - Product Control Common Template — [product-control-common-template@finos.org](mailto:product-control-common-template+subscribe@finos.org) - Reg Tech Council — [rtc@lists.finos.org](mailto:rtc+subscribe@lists.finos.org) - Regulation Innovation SIG — [open-regtech-sig@finos.org](mailto:open-regtech-sig+subscribe@finos.org) - SDLC Framework — [sdlc-framework@lists.finos.org](mailto:sdlc-framework+subscribe@lists.finos.org) - Security Reference Data — [data-tech-sec-ref@finos.org](mailto:data-tech-sec-ref+subscribe@finos.org) - Symphony Projects — [symphony@finos.org](mailto:symphony+subscribe@finos.org) - Technical Oversight Committee — [toc@lists.finos.org](mailto:toc+subscribe@lists.finos.org) - Vuu Announcements — [vuu-announce@lists.finos.org](mailto:vuu-announce+subscribe@lists.finos.org) - Vuu Discussions — [vuu-discussion@lists.finos.org](mailto:vuu-discussion+subscribe@lists.finos.org) - Vuu Questions — [vuu-questions@lists.finos.org](mailto:vuu-questions+subscribe@lists.finos.org) - Waltz — [waltz@lists.finos.org](mailto:waltz+subscribe@lists.finos.org) - Zenith — [zenith@lists.finos.org](mailto:zenith+subscribe@lists.finos.org) ### Online Chat #### Slack FINOS hosts a Slack instance on [finos-lf.slack.com](https://finos-lf.slack.com); if you are [FINOS Member firm](https://finos.org/members), you should be able to self-subscribe to access our [FINOS Community Channel](https://finos-lf.slack.com/messages/finos-community/) or you can request access to [help@finos.org](mailto:help@finos.org). #### Symphony Many members of the FINOS community use the [Symphony](http://symphony.com/) platform for regulated, secure online chat, and we encourage all community members who have a Symphony account to enable their account for "external communications" and ideally to "multi-party chats". This way you will be discoverable to other members of the community, and can initiate and participate in secure and compliant online chats. If you are a FINOS Member please email [membersuccess@finos.org](mailto:membersuccess@finos.org) if your compliance department has any questions on the nature of our chats. ### Foundation Team #### FINOS Member Success and Support If you are a FINOS Member and have questions about your status or membership benefits, email [member-help@finos.org](mailto:member-help@finos.org). #### General Help For general question, or if you are unsure who to ask, please email [help@finos.org](mailto:help@finos.org) and we will help you navigate the community. #### Infrastructure Support If you need infrastructure support for your Program, Project, or Working Group, please raise a HELP issue in the Foundation's issue tracker, or email [help@finos.org](mailto:help@finos.org). #### Individual Staff Members Please refer to the [FINOS team](https://www.finos.org/team) and [contact](https://www.finos.org/contact-us) pages on the website. --- ## Lead ### How can you become a FINOS Community leader? As you start [consuming](https://community.finos.org/docs/journey/consume) and [contributing](https://community.finos.org/docs/journey/participate) to FINOS projects, there are multiple ways for you to become a leader in our community: - Become a [FINOS Project Maintainer](#leadership-through-maintainership) - Your company can fund [FINOS through Membership](#leadership-through-membership) - Provide [feedback and enhance our governance & documentation](https://github.com/finos/community/issues)  - Organize or speak at an [FINOS Open Source in Finance Meetup](/docs/growing-your-project-community/meetups) - Speak or sponsor our [Open Source in Finance Forum](https://events.linuxfoundation.org/open-source-finance-forum/) ### Leadership through maintainership Open Source is the culture of the doers and everyone has an opportunity to become a FINOS contributor and then maintainer, through a meritocratic process of governance by contribution. As you [increasingly contribute to FINOS](/docs/journey/participate), we encourage to consider taking on more influence / responsibility by becoming a FINOS maintainer. If you are already a [FINOS contributor or maintainer](https://metrics.finos.org/), we deeply thank you for your support. It is leaders like you who drive FINOS' success. #### What's FINOS Project Maintainer? Each FINOS software project has a community of [participants](https://github.com/finos/software-project-blueprint/blob/main/CONTRIBUTING.md#roles), also referred to as "contributors", and [maintainers](https://github.com/finos/software-project-blueprint/blob/main/CONTRIBUTING.md#roles). Each FINOS standard projects has a community of [participants, editors and maintainers](https://github.com/finos/standards-project-blueprint/blob/main/GOVERNANCE.md#1-roles). A **maintainer** is a contributor who, by virtue of their contribution history, has been given [write access](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization#repository-roles-for-organizations) to project repositories and may approve and merge contributions to the project. #### How do I become a maintainer? There two ways an individual can become a FINOS Maintainer: 1. By being the proposed initial maintainer [of new project contribution accepted into FINOS](/docs/governance/Software-Projects/contribution#contribution-of-an-existing-code-base-into-finos-as-a-new-project) 2. By being nominated by an existing project's maintainers, based on extensive contributions to the project. FINOS strongly encourages projects to have multiple maintainers from multiple organizations: in fact, having multiple maintainers is a pre-requisite for the [Graduation](https://community.finos.org/docs/governance/lifecycle-stages/graduated) project [lifecycle maturity level](https://community.finos.org/docs/governance/project-lifecycle). In the case of large maintainer teams, maintainers should consider electing one or two **lead maintainers**. The lead maintainer(s) are the project's interface with the FINOS Team and Governing Board and are responsible for communicating on behalf of the project. The lead maintainer(s) are also accountable for steering project direction and prioritisation with the rest of the project community, and to build consensus. #### How does FINOS support maintainers? To support you in your leadership capacity, we've prepared a [FINOS Maintainers Cheatsheet](https://community.finos.org/docs/finos-maintainers-cheatsheet/) that is intended to be a one-stop reference for all of the responsibilities, governance activities, and support tools used by the Foundation. Our [Community Growth best practices](https://community.finos.org/docs/growing-your-project-community/finos-community-strategy/) are also a great resource to build a lively community. And of course don't hesitate to [get in touch with Foundation staff](mailto:help@finos.org) if you need help in maintaining your project. ### Leadership through Membership The FINOS community and operations are funded by [FINOS corporate members](https://finos.org/members). We are thankful and proud to have a diverse community of financial services and technology organizations shaping the future of open innovation in financial services. Learn about [FINOS Membership Benefits](https://www.finos.org/membership-benefits?hsLang=en-us) and get in [touch with us](https://www.finos.org/membership-benefits#become-a-member). If you are a [FINOS member](https://finos.org/members), welcome and thank you! --- ## Learn If you are new to FINOS, new to Open Source, or working for an organization looking to accelerate their open source consumption and contribution, FINOS hosts a set of free and member-only resources, as well as meetings, events and other venues for financial services developers and subject matter experts to fully embrace the benefits of open source. Additionally, FINOS provides access to self-serve and interactive channels to learn about the FINOS Community and projects as well as about our governance. ### Not sure where to get started? Here are some suggestions to kick off your FINOS journey: - Join the [Community Mailing List](mailto:community+subscribe@finos.org) and/ or the [FINOS Member-only mailing List](mailto:member+subscribe@finos.org) if you are an employee of a [FINOS Member](https://finos.org/members) - Join our [Slack channels](https://finos-lf.slack.com/messages/finos-community/) (email [help@finos.org](mailto:help@finos.org) if you have issues joining) - Learn about [FINOS Projects & Special Interest Groups](http://landscape.finos.org/) and a [Project or SIG Meeting](https://www.finos.org/calendar) - Learn about the FINOS [Open Source Readiness Initiative](https://finos.org/open-source-readiness) and join [Open Source Readiness Special Interest Group (SIG)](https://osr.finos.org) meeting to improve your firm's participation to Open Source - Learn [how the FINOS Community is governed](/docs/governance) - [Get in touch with the FINOS team](https://www.finos.org/contact-us?hsLang=en-us) or join [FINOS Office Hours](https://calendar.google.com/event?action=TEMPLATE&tmeid=MXVuM2xpNmc5ajRtaXExNnFrZWEyZGo3aXVfMjAyMjA0MTNUMTUwMDAwWiBmaW5vcy5vcmdfZmFjOG1vMXJmYzZlaHNjZzBkODBmaThqaWdAZw&tmsrc=finos.org_fac8mo1rfc6ehscg0d80fi8jig%40group.calendar.google.com&scp=ALL) with our Community Management team ### Amazing resources for you to learn more - Check out our [FINOS Knowledge Base](https://www.finos.org/knowledge-base) - Listen to the [FINOS Podcast](https://podcasts.apple.com/us/podcast/finos-open-source-in-finance-podcast/id1512371068) - Browse the [FINOS Youtube Channel](https://www.youtube.com/c/FINOS) - Read our [FAQ](https://www.finos.org/faq) - [Sign up for FINOS updates](https://www.finos.org/sign-up) - Follow us on [X](https://twitter.com/finosfoundation) or [LinkedIn](https://www.linkedin.com/company/finosfoundation/) ### Need help? Email [help@finos.org](mailto:help@finos.org) and we will be in touch shortly --- ## Contribute ### Quickstart If you want the tl;dr of how to start contributing to FINOS, a great starting point is our [Community Quickstart page](https://www.finos.org/get-involved). Also most projects will label issues with `Help Wanted` or `Good First Issue` labels, as desirable and not overly complex. Take a look at a FINOS wide list of [Good First Issues / Help Wanted](https://github.com/search?q=org%3Afinos+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22). For more information, keep reading below. ### Contributing to a Project One of the most exciting aspects of open source is that participation isn't restricted to a core development team. Anyone can contribute to FINOS projects. Fork a repository, make changes, and propose them through pull requests. FINOS governance is designed to keep collaboration transparent for individuals, financial institutions, fintechs, and technology companies alike. No paid Membership is required, and everyone is welcome to contribute to an existing project in the [FINOS landscape](https://landscape.finos.org), whether it's an [open source software (OSS) project](/docs/governance/#open-source-software-projects), an [open standard project](/docs/governance/#open-standard-projects) or a [Special Interest Group (SIG)](/docs/governance/special-interest-groups/). ### Open Source Software Projects #### Contributing to an existing Software Project 1. Choose a project in [our Landscape](https://landscape.finos.org/) or if you don't know where to start, take a look at the list of [Good First Issues on Github](https://github.com/search?q=org%3Afinos+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) where projects are actively seeking for help! 2. Take a look at how to [contribute to an existing project ](/docs/governance/Software-Projects/contribution#contribution-of-code-to-an-existing-finos-project) 3. You or your company will need a valid [Contributor License Agreement](/docs/governance/Software-Projects/contribution-compliance-requirements#contributor-license-agreement), which can be easily completed online via [EasyCla](/docs/governance/Software-Projects/easycla) > The Foundation also encourages non-code contributions in the form of issues - bug reports and enhancement requests -, and documentation updates. > This means that **you do not need to be a developer to contribute to FINOS projects**. These are also highly valued contributions, and project teams > appreciate non-code contributions just as much as code-level contributions. ##### Project specific guidelines Some projects may have additional contributing guidelines and requirements; such as requiring a particular coding standard or following a specific review process. In order to maximize the chances of your contribution being accepted, take a look at the `CONTRIBUTING.MD` file of the project you are contributing to. The [Contributor Cheat Sheet](/docs/finos-contributors-cheatsheet) is a great resource to help here. #### Contributing a new Software Project FINOS follows a formal structured process of proposal, community socialization and approval for our projects. Take a look at [how to contribute a new project to FINOS](/docs/governance/Software-Projects/contribution#contribution-of-a-new-FINOS-project-or-SIG). If/ once the project is approved, the FINOS team will create the project based on the [Software Project Blueprint](https://github.com/finos/software-project-blueprint) to jumpstart your project with proper contribution guidelines. **NOTE**: Only FINOS Members are allowed to propose new contributions or you will need at least one Member to support / vouch for your contribution. ### Contributing to an Open Standard project Given their non-code nature, FINOS [Open Standard projects](https://landscape.finos.org/?license=csla-1-0,finos-ip-policy,isda-developer-license) follow a [different governance](https://community.finos.org/docs/governance/#open-standard-projects) and rules for participation will be documented in the standard specific documentation. Once you have identified a project you'd like to participate in, take a look at [the FINOS Community calendar](https://www.finos.org/calendar) to attend the next standards meeting. Agendas will typically be published in advance in the project GitHub issues. ### Participating in a Special Interest Group (SIG) FINOS Special Interest Groups (SIGs) bring together financial services participants to discuss common challenges, use cases, and collaboration opportunities. Your input helps shape and prioritize foundation activities. Everyone can join a SIG by subscribing to the SIG mailing list and attend the group's scheduled [meetings](https://www.finos.org/calendar). For a list of active SIGs refer to the [SIGs page](/docs/governance/special-interest-groups) or the [FINOS landscape](https://landscape.finos.org/). [SIG governance is intentionally lightweight](/docs/governance/#special-interest-groups). Each SIG is expected to document its target audience, mailing list details, and meeting information in its [GitHub repository](https://github.com/finos/). SIGs may create and enforce additional desirability criteria for participants; an example might be to require a particular area of industry expertise (e.g., interest rate swaps) or knowledge of a programming language (e.g., C++) or library. These criteria should also be clearly documented on the SIG's documentation page. ### Contribute to our blog A great way to contribute besides code, issues or documentation is to contribute content to our [Community blog](https://www.finos.org/blog) - we welcome FINOS projects related topics (technical or not) and more broadly open source topics relevant for the financial services industry. Send your proposed article to [marketing@finos.org](mailto:marketing@finos.org). --- ## FINOS Legend Studio Shared instance [Legend](https://github.com/finos/legend) provides an **end-to-end data platform experience covering the full data lifecycle**. It encompasses the [**Legend-Pure language**](https://github.com/finos/legend-pure) and a suite of data management and governance tools known as the **Legend Platform**, which allows engineers and non-engineers alike to describe, connect, visualize, and query high-quality data. **Learn more about Legend at [legend.finos.org](https://legend.finos.org).** ### Shared Public Instance of Legend Studio FINOS hosts a shared instance of Legend Studio at [https://legend.finos.org/studio](https://github.com/finos/legend-studio). The shared instance of Legend Studio is provided free-of-charge and as-is. It is primarily intended to be used for shared modeling efforts conducted by FINOS members and other non-member community participants as part of [FINOS hosted projects or initiatives](https://landscape.finos.org/). Learn about the projects that are currently leveraging the shared instance of Legend Studio in the "modeling initiatives" section of the [FINOS Landscape](https://landscape.finos.org/). The shared instance was also used by participants in the [FINOS Legend Studio pilot (April-September 2020)](https://www.finos.org/press/goldman-sachs-open-sources-its-data-modeling-platform-through-finos). Anyone is welcome to [request an account on the shared instance](https://www.finos.org/legend). Requests for accounts will be fulfilled based on FINOS staff availability as well as the rationale stated below for wanting an account and/or any connection between a request and the work of an ongoing FINOS project. Additional consideration will be also given to account requests from FINOS members. #### Default project configuration and permissions Legend models developed on the [FINOS hosted shared instance of Legend Studio](https://github.com/finos/legend-studio), are open source and map to a GitLab project within the https://gitlab.com/finosfoundation/Legend group. **Configuration**. All projects in the https://gitlab.com/finosfoundation/Legend group are subject to the following configuration: - `master` branches are protected from direct commits, only Merge Requests are allowed - Merge Requests must be approved by at least one project Code Owner **Access, roles and permissions**. Anyone interested can request access to the shared instance of Legend Studio by filling out the form at https://www.finos.org/legend. Access to the shared instance of Legend Studio will be associated to one of the following roles and permission levels: - `Reporter`: is the default permission level provided to anyone requesting an account on the shared instance of Legend Studio. Users with reporter access can read [Legend workspaces](https://legend.finos.org/docs/tutorials/studio-workspace) across all FINOS hosted models. - `Developer`: users with developer access can create [Legend workspaces](https://legend.finos.org/docs/tutorials/studio-workspace) and submit changes across all FINOS hosted models. A prerequisite to get `developer` access is to meet FINOS [contribution requirements](/docs/governance/Software-Projects/contribution-compliance-requirements) (including CLA where applicable) for the project. - `Maintainer`: users with maintainer access can review merge requests and merge changes. A prerequisite to get `maintainer` access is to meet FINOS [contribution requirements](/docs/governance/Software-Projects/contribution-compliance-requirements) (including CLA where applicable) for the project. `Maintainers` are elected according to the steps set out in the [FINOS Governance](https://github.com/finos/software-project-blueprint/blob/main/CONTRIBUTING.md) Maintainers can be: - `Legend Maintainers`: they lead the Legend project and have Maintainer access across all models - `FINOS Modeling Project Maintainers`: they lead one specific project in FINOS, which includes Legend modeling initiatives; they are granted `Maintainer` roles across all the modeling initiatives within that FINOS project - `Model Maintainers`: they lead one specific modeling initiative, as part of a FINOS project ### Background [Legend](https://github.com/finos/legend) was originally developed by Goldman Sachs and contributed to FINOS in October 2020. See the October 2020 [Open Sourcing Press Release](https://www.finos.org/press/goldman-sachs-open-sources-its-data-modeling-platform-through-finos), and coverage in Business Insider ["Code for Goldman Sachs' internal data platform is now open for anyone to use"](https://www.businessinsider.com/code-for-goldmans-data-platform-legend-open-sharing-github-2020-10), and Bloomberg ["Goldman Sachs Open Sources its Data Modeling Platform through FINOS"](https://www.finos.org/press/goldman-sachs-open-sources-its-data-modeling-platform-through-finos). --- ## Symphony Developer Pod As part of the Symphony Partner Program, FINOS has access to the Symphony Developer Pod and can provide (shared access to) user and service accounts for project teams that are working on Symphony bots, app, or integrations. For user accounts, username and passwords will be provided, to login via https://develop.symphony.com For service accounts, certificates and passwords will be provided; please follow https://docs.developers.symphony.com/ to access developers documentation. FINOS can provide 2 user and 2 service accounts, but any team member who is a [Symphony Certified Developer](https://symphony.com/support/developers/) can request one additional user and service account. --- ## FINOS Project Sandbox The FINOS Project Sandbox allows [FINOS open source projects](https://landscape.finos.org) to host a public runtime environment to serve different purposes, like enabling easy evaluation, public collaboration or delivering real life demo environments. The FINOS technology team provides infrastructure and operational support to project maintainers, enabling them to focus on development rather than operations. You can read more on [www.finos.org/project-sandbox](https://www.finos.org/project-sandbox). For the Legend Shared instance - our first and most used project sandbox - we have documented the setup on [community.finos.org/docs/platforms/legend-studio-shared](https://community.finos.org/docs/platforms/legend-studio-shared/). --- ## Foreword The purpose of this document is to propose simplifications to the governance of FINOS projects. We’ll discuss several issues with the existing governance structure and propose a simplified structure reducing hierarchy and bureaucracy. ## Motivation When the Symphony Software Foundation was reorganized as FINOS in April 2018, a governance structure for collaborative community projects was instituted. Projects and working groups (now collectively known simply as “projects”) were organized into high-level “programs” grouping projects focused on the same problem domain (e.g. Data Technology) or technology (e.g. Symphony). Programs were designed to be self-governing, managed by a Program Management Committee of contributors to the projects within each program. Programs were required to abide by the high-level governance requirements of the FINOS Program Governance Policy (PGP) and to adopt a Program Operations Policy (POP) setting out their own particular operational rules. (Most adopted the “standard” POP recommended by the Foundation.) This governance structure was largely borrowed from other open source foundations with mature projects produced by many active contributors experienced with open source collaboration. FINOS is different: our members are still new to open source collaboration and many FINOS projects are experimental or less mature. For many participants, the projects they contribute to are not essential to their daily work, so participation in FINOS governance is extra work with little reward. Strict requirements to constitute a PMC, hold meetings, and report regularly on program activity can be burdensome or pointless for programs whose projects are loosely connected and immature. Additionally, in July 2019 the Board of Directors approved a revision of the project lifecycle which identified objective criteria of quality, activity and viability for projects to transition into incubating, graduated and archived state. The goal was to provide a meta-roadmap for each project to become a successful pan industry open source effort while allowing a clear differentiation (for consumers primarily and for contributors) between nascent (Incubating) and mature (Graduated) projects. Like in most OSS Foundations, the project lifecycle should have a central role in the project taxonomy. ## Background The table below details how the existing governance structure has failed to operate as expected: Expectations | Experience Programs are self-governing on technology and lifecycle matters | Programs have become a governance overhead for FINOS and PMCs PMCs are in charge of nurturing their own Projects through the lifecycle | PMCs are not mature or engaged enough and responsibility falls on FINOS Programs consolidate common activities around a theme/business problem | Projects within programs are often loosely related. Concept of programs is a barrier of entry for new contributors. Programs are a governance only structure | Program quickly got conflated within the FINOS messaging, which became more complex, and effectively became a strong partition of the project portfolio which limits organic evolution and growth in new areas. Membership to a PMC is a highly regarded responsibility and incentive for contributors to take a leadership role | Only few PMCs have been functional with their members taking an active role ## Proposal 1. **Do away with programs and PMCs**: Projects will live at top level. They can still be categorized around similar themes and areas of interest in Github (theming / tagging) and other web properties. 2. **FINOS approval role in software projects**: FINOS team approves new software projects and lifecycle transitions, based on objective criteria of [Incubating](/docs/governance/lifecycle-stages/incubating) and [Graduation](/docs/governance/lifecycle-stages/graduated). An appeal process to the Board is provided to contributors and community members to ensure impartiality and appropriate checks and balances. 3. **Board input can be optionally requested**: FINOS team can decide to bring projects to the Board for approval into incubation (contribution) or other lifecycle transitions (graduation/archival), to ensure initial industry wide buy-in as well as appropriate validation of the maturity state of a project. Board approves transition of incubating projects to “Graduated” state when they demonstrate the required level of maturity. 4. **Clarify Foundation focus and investments**:** **FINOS focuses on “coaching” incubating projects, while focused “marketing” efforts on graduated projects. In this sense, FINOS team’s open source coaching is directed more towards incubating projects, while marketing investment is directed more towards graduated projects (the crown jewels). The expected benefits of this simplification are as follows: Benefit | How? Drive allocation of FINOS resources | Marketing focus only for "Graduated" projects. Coaching / support focus for "incubating" projects. Reduce contribution friction | FINOS can approve new "Incubating" projects directly, removing need for PMC approval or other governance process Reduce governance overhead | Remove need for aggregated quarterly program-level reporting. Projects can report in a largely automated and independent fashion. Avoid speculative projects | To promote sustainability and resource stewardship, FINOS will heavily validate initial buy-in from Community and board on "industry-wide" efforts (e.g. standards), thus promoting focus on valuable and viable efforts Drive banks' member engagement | For industry-wide projects (e.g. standards), FINOS will require bank SME engagement to establish projects ## Implementation Implementation of these changes requires changes to the following FINOS governing documents: ### Policies * **Bylaws** * Section 4.1(b)(ii): remove reference to Programs (and working groups) * Section 6.2: remove this section entirely * The **Program Governance Policy** will be eliminated entirely. None of its requirements are necessary once programs are eliminated. * The **Program Operations Policy **will be eliminated. The following provisions should be adapted and moved to a separate FINOS policy (e.g. a “Project Operations Policy”): * Section II(C), setting out the procedure for approving new projects * Most of Sections III (Collaborative Principles) and IV (Projects) can be moved to the Community Handbook as statements of best practices for operating a project, but need not be strictly required. Section III(A)(a), requiring projects to enforce FINOS IP policies, is unnecessary because the Community Handbook already addresses these issues and FINOS staff enforces the IP policies. * The **IP Policy** will be revised to remove references to Program Operations Policies and to add the requirement of board approval for standards projects. * The **Trademark Guidelines** will be revised to remove references to programs. * ### Web Properties #### Messaging and Web properties The removal of Programs will allow centering the FINOS messaging and web properties around: 1. Project Lifecycle: Graduated projects will be given central visibility on website, project catalog and other FINOS web properties. Incubating project will be listed in the project catalog and organized in a simplifies taxonomy for easier discoverability 2. Functional taxonomy: With Program removed, FINOS will be able to implement a multi-dimensional taxonomy (e.g. tagging) allowing to simplify discovery of FINOS projects based on their functionality and / or position in the financial stack. This taxonomy will be validated with the Community and then implemented across web properties 3. User centric messaging: FINOS web properties will be restructured to put the different target personas (consumers, contributors, etc.) front and center and enable discovery of high value projects solving problems for specific personas. #### Source Code repositories The process of consolidation of source code repositories into the main FINOS Github Org is expected to continue with the removal of programs. Repositories will be tagged appropriately to reflect the functional taxonomy (#2 above) and optionally map into the user centric messaging (#3). The FINOS catalog will be updated accordingly. #### Wiki The Wiki is currently organized around the Program construct. Whether the wiki remains on Confluence or moves to Github, a major wiki content overhaul is to be expected to align to the new governance: * The Community Handbook will be revised throughout to remove references to programs, incorporate the new procedures for lifecycle transitions listed above, and incorporate elements of the standard POP.Remove Program structure and align to functional taxonomy above ### Process 1. **Early Jan:** Internal review (AaronW, Tosha, Gab, James) 2. **Mid Jan:** M&G Committee review 3. **Mid Jan: **Community RFC starts 4. **Late Jan: **Board approves a “blanket” resolution giving FINOS team green light to proceed 5. **Early Feb:** Community RFC end and comments are incorporated 6. **Feb - April: **Operationalization 7. **Late April: **Board final policy approvals / cleanup