Collaboration Infrastructure | FINOS Community

Collaboration Infrastructure | FINOS Community
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.
important
If you're a maintainer of a FINOS hosted project and need infrastructure that is not documented here, please
contact 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:
Create an account on GitHub.com
Setup a Git client locally
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:
Your corporate firewall blocks Git activity, unless you have signed in with an
@
email address.
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:
Checkout the source code
Consume any artifact produced by a Project
Access
FINOS Kanban boards
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:
Become a member of the FINOS GitHub Organization
Submit a code change via
Pull Request
FINOS uses GitHub 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
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
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 invited to the
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:
Access
Search for your name or GitHub username
Open the dropdown close to Private
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:
Lead Maintainers have the ability to add new maintainers (aka GitHub Team maintainer)
Project maintainers can vote to add/remove team members
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
; each FINOS project code can be spread across different repositories, you can check the
FINOS Landscape
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
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
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
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
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:
Direct commits are not validated, as they cannot be blocked (ie, if
CLA
is not in place)
Pull Requests allow to have a conversation with the team
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:
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).
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:
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)
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.
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
, with the following limitations:
The scope of the conversations is always public, whereas there may be sensitive conversations across project leaders that may require to be confidential
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
A more advanced way is to use
GitHub Team Discussions
Can be created as private, which are accessible only by team members
Can be created as public to all GitHub FINOS org members
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
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
. 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
. 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
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:
Project Maintainers vote for accepting new members to their teams
Project Maintainers vote to manage releases and other decide on any other decisions
GitHub Issues can provide an easy platform to vehicle this process:
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
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)
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:
A Github repository
The
vote
issue label defined
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:
A Github repository
The meeting leader must have at least
Write
access to the repository
The
meeting
issue label defined
Issue template
.github/ISSUE_TEMPLATE/Meeting.md
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
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
FINOS Project blueprint
Project blueprint
is a FINOS project that provides a template for new or existing repositories; it includes:
README.md template
, with a suggested structure of content
NOTICE template
, required by FINOS bylaws
LICENSE template
, required by FINOS bylaws
Code of Conduct
template, required by FINOS bylaws
Contributing guidelines
, required by FINOS bylaws
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
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:
Make sure that your GitHub repository includes the
docs/
and
website/
folder from the
project-blueprint
Read our
getting started guide
to understand more about Docusaurus`
How to use this blueprint
Visit on
Click on
Use this template
and follow instructions
Copy the
README.template.md
file to your repository, and rename it to
README.md
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
software-project-blueprint
{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).
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
Open the
README.md
file in a text editor and complete the content as appropriate for your project.
Add the
Apache license header to all of your source files
(optional) Remove
.whitesource
and
whitesource.config
, if vulnverability detection does not apply to this project
(optional) Remove the
docs/
and
website/
folders, if you're not interested to have a project documentation website in place
Commit and push all of your changes.
Automated and continuous quality scanning
FINOS provides some examples on
to run continuous code scanning activities. More tools are also documented on the
code validation page
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.
GitHub Account Setup
Access Control
GitHub Member VS FINOS Member
Becoming GitHub FINOS Organization member
Public VS Private Membership
Teams
Useful links
Collaboration use cases on GitHub
Code hosting
Accepting Code Contributions
Managing Issues
Project Releases
Project Website
Conversations
[DEPRECATED] GitHub Team Discussions
FINOS Slack
Voting
Meeting Minutes
Security Scanning
FINOS Project blueprint
Automated and continuous quality scanning
Other collaboration use cases
Meeting Management
Mailing Lists (Google Groups)
Contacting the FINOS team
Private or Sensitive Information