Collaboration Infrastructure

FINOS leverages many services offered by GitHub.com, which are documented in the Collaboration Use Cases on GitHub and 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 and sign the FINOS Contributor License Agreement (CLA); this document will walk you through access control and permissions that are enforced on FINOS GitHub properties.

info

If you're a maintainer of a FINOS hosted project and need infrastructure that is not documented here, please open a issue on ODP, 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

2. Setup a Git client locally

3. Ensure that the Git client is configured with your <username>@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 @<your company domain> 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 open (public); as a consequence, anyone is able to:

1. Checkout the source code
2. Consume any artifact produced by a Project
3. Access FINOS Kanban boards
4. Use GitHub Issues to contribute to the discussion (a GitHub account is required)

Any GitHub user covered by a Contributor License Agreement with FINOS can also:

1. Become a member of the FINOS GitHub Organization
2. Submit a code change via Pull Request

FINOS uses GitHub Teams to manage committers team for each project, which are the only ones allowed to make direct changes to project repositories. You can read more about FINOS teams below.

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 the FINOS CLA bot)
		Use GitHub Issues to contribute to the discussion
GitHub user covered by CLA	Read	Become a member of the GitHub FINOS Organization
		Submit a code change via Pull Request (validated by the FINOS CLA bot)
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 to know more about entitlements.

GitHub Member VS FINOS Member

Please note, FINOS Members are organizations that provide industrial and financial support to the FINOS through their platinum, gold, and/or silver membership fees, and through their participation in the FINOS Governing Board. Members of the FINOS GitHub Organization are individuals, represented by a GitHub Profile and a signed FINOS Contributor License Agreement (CLA).

Becoming GitHub FINOS Organization member

Assuming that you have read our Contribution Compliance Requirements and have a CLA signed with FINOS, you can request to be invitated to FINOS GitHub Organization by emailing your GitHub username to 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
• About GitHub Teams
• Other GitHub guides

Collaboration use cases on GitHub

Code hosting

Code in the Foundation is hosted exclusively on https://github.com/finos, with exception for Hadouken and Symphony initiatives, which use dedicated GitHub Organizations, see below. These orgs are still managed by FINOS and share the same configuration, which is documented in this page.

Initiative	GitHub Organization
Hadouken	https://github.com/HadoukenIO
Symphony	https://github.com/symphonyoss
others	https://github.com/finos

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.

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 and metrics dashboards.

Building and testing

The build is an end-to-end process that converts source code into reusable artifacts, something that we will refer to as deployable units, which is developed by the project team and hosted in the github repository. It is a particularly important task, as it can centralise and trigger several automated sub-tasks, such as version control, code testing, quality and compliance reports and more.

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 activation.

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 ("semver") throughout a project's lifecycle:

• for incubating projects, version numbers must be less than 1.0.0
• for Active 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 is not in place)
2. Pull Requests allow to have a conversation with the team
3. Pull Requests tent 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 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 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 minute
  - vote - If an issue describes a vote
  - indexed - When meeting attendance (assignees) is tracked
- Topics - #ffd4b7
  - github - GitHub related topic
  - docusaurus - Docusaurus related topic

Project Releases

The easiest way to define roadmaps in GitHub is using Milestones, which allow to group issues together and associate a title, description and due date.

As a complement or alternative, GitHub 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.

FINOS uses a framework called Docusaurus to build a website template that any project can adopt; this website is an example. The advantages of having a centralised strategy for project documentation includes:

1. Ease of use - Markdown file syntax, simple local development, easy configuration.
2. Easy to collaborate - Files are stored in a docs/ GitHub repository folder, anyone can submit a Pull Request.
3. Automated - any change to the master branch version will trigger a deployment of the website, using the Docusaurus build action; also forks can enable this action, so that Pull Request submitters can provide a link to their preview website.
4. Branded - enforces FINOS graphic guidelines across all websites

If you want to add a website to an existing project, checkout the ODP Project Documentation; if you are starting a project from scratch, checkout the FINOS project blueprint.

Checkout FDC3 and Financial Objects as other examples.

[DEPRECATED] Docusaurus Build Action

Note! This GitHub action has been deprecated in favor of using Netlify

The docusaurus workflow defines a GitHub Action that automatically builds the Docusaurus website after any commit.

If a Push event occurs on the a Docusaurus file (website/**, docs/** or docusaurus.yml) on a FINOS master branch, the action will simply invoke the docusaurus-build command and push the (HTML) result into the gh-pages branch.

If the Push event occurs on a fork of a repo with this action, the same workflow will follow, and the Docusaurus configuration (siteConfig.js) will be patched prior to the build, in order to serve the pages using the personal GitHub account that forked the repo.

If a Pull Request is submitted (related to Docusaurus files) against a FINOS repository with this action, beyond following the process described above, the action also adds a comment to the PR with the link to the preview website, containing the changes to the PR (still work in progress).

IMPORTANT! After forking the repository, make sure to enable the action, by accessing the Actions tab on your fork; Actions of forked repos are not enabled by default for security reasons.

You will need to either update file in the docs/ or website/ folder (only on master branch) in order to trigger a build.

No other configuration is needed, it should work out of the box.

Conversations

In order to track threaded conversations - among FINOS Project / SIG team members, external collaborators and consumers - it is possible to use GitHub 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.

GitHub Team Discussions

A more advanced way is to use GitHub Team 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.

Both features support email notifications and the ability to post a comment by answering to it. Simply raise a FINOS Slack Channel / GitHub Team Discussions Request to enable GitHub Team Discussions for FINOS Project and SIG teams.

FINOS Slack

The FINOS Slack brings the FINOS Community together in a Slack Workspace dedicated to "public" conversations and made available to all FINOS Projects and Special Interest Groups.

Join the FINOS Project, SIG and wider community conversation in the FINOS Community Slack. If you are an employee of a FINOS Member, 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 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, simply raise a FINOS Slack Channel / GitHub Team Discussions Request 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, the FINOS Community Code of Conduct and all other FINOS 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 (see ODP issue template as example). 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; you can read more in the Running Good Meetings page; they are also very important for participants, as they are used to track meeting participation and therefore the activity of each individual and firm; all data is publicly available at metrics.finos.org

FINOS provides a way to use GitHub Issues to manage meeting minutes. The person leading the meeting (or meeting leader) can create a new GitHub Issue for each meeting, following the Meeting template provided by FINOS and leverage issue assignees to track meeting participants (see our public activity dashboards).

• Prior to the meeting - 48 hours before, as per meeting best practices, the meeting leader creates a new GitHub Issue using...
  • Meetings issue template
  • [MEETING] title prefix
  • meeting label
• At the beginning of the meeting - the meeting leader posts the issue URL on the meeting chat and asks all participants to add a comment on the issue
• At the end of the meeting - the meeting leader closes the issue, which will trigger the attendants the indexing process; when indexing is completed, the label indexed will be added to the issue.
• (Optional) After the meeting - the meeting leader can remove the indexed label in order to remove meeting attendance from the index and make changes; in order to reindex the meeting, the indexed label can be re-added.

Corner cases

• If a GitHub username cannot be added as issue assignee, it means that is not part of github.com/orgs/finos/people (the GitHub FINOS Org members); to work around this restriction, the GitHub user can add a hello comment to the issue, which will allow the meeting leader to do the assignment. In parallel, the GitHub user can sign a CLA with FINOS and request GitHub Org membership.
• If a participant doesn't have a GitHub account, the meeting leader can add full name and affiliation in the issue description (see issue template).
• If a GitHub username is not registered on FINOS internal database, it won't be indexed; in that case, the action will add a comment to the issue, with the list of users not being indexed and a mention to FINOS staff team.
• Never reopen and close a meeting minutes issue! If a meeting issue is reopened and closed, after the meeting is held, the meeting date will be overridden with the current one ; if you need to reindex a meeting, indexed label as described above. If you're uncertain or want to revert changes, get in touch with FINOS staff via help@finos.org.

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.md defined
5. [DEPRECATED] Action .github/workflows/meetings.yml defined
6. GitHub repository secrets (ask help@finos.org to set them up)

Security Scanning

In order to consolidate processes and tools around security vulnerabilities management, FINOS have shared a guidelines around responsible disclosure for security vulnerabilities and teamed up with WhiteSource to configure a bot that continuously scans - across each configured repository - all external dependencies; the bot is able to scan direct commits and Pull Requests, and by default creates GitHub Issues with details about the vulnerability; you can read more about WhiteSource integration for GitHub.com.

FINOS Project blueprint

Project blueprint is a FINOS project that provides a template for new or existing repositories; it includes:

1. A README.md template, with a suggested structure of content
2. A NOTICE template, required by FINOS bylaws
3. A LICENSE template, required by FINOS bylaws
4. A Code of Conduct template, required by FINOS bylaws
5. Contributing guidelines, required by FINOS bylaws
6. Issue templates for bugs, feature requests and support questions , defined in the .github folder

Placeholders are defined using the {} brackets.

Creating a new repository

Anyone can use the Project blueprint repository, simply accessing https://github.com/finos/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 (1.14) and served via https://finos.github.io/<repository name>.

info

If you don't need or like the documentation website provided by the FINOS blueprint, simply ignore, skip or delete the website/ and docs/ folder.

Getting started is quite simple:

1. Make sure that your GitHub repository includes the docs/ and website/ folder from the project-blueprint
2. Read our getting started guide to understand more about Docusaurus
3. Edit website/siteConfig.js following comments in file
4. Install the Docusaurus Build Action provided by FINOS
5. Make edits on docs/ files and check changes on https://finos.github.io/<reposirory name>.

How to use this blueprint

1. Visit on https://github.com/finos/project-blueprint

2. Click on Use this template and follow instructions

3. Copy the README.template.md file to your repository, and rename it to README.md.

4. Search and replace the following tokens in the newly copied files:

   Token	Replace with
   {project name}	The name of the FINOS Project, ie Open Developer Platform
   {project slug}	The name of the GitHub repository the project resides in, ie open-developer-platform
   {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).

5. Open the NOTICE file in a text editor and either remove the {Other notices, as necessary} token, or add attributions if required by your code's dependencies.

6. Open the README.md file in a text editor and complete the content as appropriate for your project.

7. Add the Apache license header to all of your source files.

8. (optional) Remove .whitesource and whitesource.config, if vulnverability detection does not apply to this project

9. (optional) Remove the docs/ and website/ folders, if you're not interested to have a project documentation website in place

10. Commit and push all of your changes.

Automated and continuous quality scanning

The ODP team is working on a GitHub action to continuously check all FINOS repositories against FINOS bylaws and requirements; see https://github.com/finos/open-developer-platform/issues/31 to know more.

Other collaboration use cases

Meeting Management

FINOS can facilitate the scheduling of web meetings for our hosted projects and SIGs, using the Zoom platform. While we work on the integration of the LFX platform specifically the Project Control Center Meeting Mangement tool, please email help@finos.org to request assistance.

Mailing Lists (Google Groups)

The Foundation provides mailing lists via the Google Groups service. 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.

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.
• 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.

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. 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.