Project Collaboration

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 collaborate in a FINOS project, the first thing is to get a GitHub.com account and sign the FINOS CLA; this document will walk you through access control and permissions that are enforced on FINOS GitHub properties.

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:

  4. Your corporate firewall blocks Git activity, unless signed with and @<your company domain> email address

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

WhoWhat
Any GitHub userFork repository
Submit a code change via Pull Request (flagged by the FINOS CLA bot)
Use GitHub Issues to contribute to the discussion
AnyoneCheckout the source code
Consume any artifact produced by a Project
Access FINOS issue boards
GitHub user covered by CLABecome a member of the GitHub FINOS Organization
Submit a code change via Pull Request (validated by the FINOS CLA bot)
FINOS StaffAdministration tasks
Monitoring
Project Maintainer (GitHub User)Approve Pull Requests
Manage releases
Manage roadmap
Manage website and other project infrastructure
Anything granted by the GitHub Maintain permission
Lead Maintainer (GitHub User)Point of contact with FINOS Staff

GitHub Member VS FINOS Member

Please note, the term FINOS Members normally refers to the firms that sit on the FINOS Board and provide industrial and financial support to the foundation. Whereas, GitHub FINOS Organization Members are individuals, represented by a GitHub Profile and a signed FINOS 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 invitation to FINOS GitHub Organization by emailing your GitHub username to help@finos.org.

FINOS uses GitHub Actions to automatically track new GitHub users (we have on file) which are covered by a CLA, and automatically sends out an invitation to join the FINOS GitHub org.

The source code is part of the FINOS Project Quality & Compliance Action.

Public VS Private Membership

public-vs-private-membershipAny 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
repo-teams

Teams

NOTE! - We're in the process of updating this configuration/documentation to reflect changes in governance after disbanding FINOS Programs.

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

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.

InitiativeGitHub Organization
Hadoukenhttps://github.com/HadoukenIO
Symphonyhttps://github.com/symphonyoss
othershttps://github.com/finos

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.

To know more about build configuration, check the Languages page.

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; browse the Languages page to know more about automated configurations for a given language.

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

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.

milestone-example

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.

fdc3-org

Docusaurus Build Action

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.

Enable GitHub Actions on a forked repo

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 (no Personal Tokens, as done in Travis CI), this should work out of the box; you can track builds on https://github.com/maoo/finos-fo/actions .

Conversations

In order to track threaded conversations - among project 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.

A more advanced way (currently being investigated at FINOS) 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.

team-page-discussions-tab

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
vote-reactions

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

meeting-issue-template-create

Meetings are one of the most used collaboration channels at FINOS, and minutes are very important, as they provide a 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

Although Atlassian Confluence is currently the most used tool, FINOS also 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.
meeting-issue

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. 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. WhiteSource custom configuration, to setup continuous security scanning for your project
  7. 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 project 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>.

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

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 resources

Other collaboration use cases

Web Conferencing (Webex)

The Foundation provides a Webex-based web conferencing facility to support online meetings. We expect FINOS projects who don't have their own Webex service to make use of this infrastructure for their regular meetings. Please email help@finos.org to request assistance with.

Why WebEx

The Foundation has determined that most other web conferencing services (including, but not limited to, GoTo Meeting, Zoom, appear.in, RingCentral, and more) are blocked by some or all of the banks that participate in our community. Webex is the only web conferencing system that is reasonably broadly supported by the banks, and in order to ensure equal access to all community members (and especially those employed by a bank), we strongly recommend using Webex exclusively for web conferencing.

That said, it doesn't have to be the Foundation's Webex account specifically - any Webex account will be equally accessible by the community.

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.

Wiki (Confluence Cloud)

The Foundation provides a Cloud-hosted instance of the Atlassian Confluence wiki for use by the community. This software provides content collaboration features, for both web content, and document-based content. Most of the content is publicly available, though it's possible to restrict access to pages.

Access to Confluence is available to the community for free - you can sign up for an account.

Accessibility issues

Please be aware that several eployees of financial institutions have experienced issues creating accounts on https://finosfoundation.atlassian.net/wiki due to compliance related restrictions applied to their corporate network.

The Project Website section documents how to Teams can also decide to use GitHub Wiki to document their project activity and publish documentation, you can read more on https://help.github.com/en/articles/about-wikis or see how some FINOS hosted projects, like the GreenKey Discovery SDK, are using it today.

Minuting Services

The Foundation offers a dedicated scribe who is available to capture the minutes of online meetings. These minutes include:

  1. the list of attendees, provided a formal roll call is conducted by the host at the commencement of the call
  2. a summary of the discussion of each agenda item
  3. any decisions reached (i.e. using the Foundation's decision making mechanism)
  4. any actions identified during the meeting

To request scribe services, please email help@finos.org and include the schedule of meetings you need assistance with. The Foundation will then confirm whether the scribe is available at that time, and provide further instructions regarding booking their time.

Content will be added to the Confluence meeting minute page containing the agenda (which must exist prior to the call - see note below), or, if you're using some other system for meeting minutes, as a Word document attachment in an email (which you will then have to copy into that system yourself).

Other important notes:

  • Minuting services are available on a first-come, first-served basis; if the scribe is already booked for a meeting at the same time as yours, they will not be available. We encourage Project maintainers to review the meeting schedules of their peers, to reduce the risk of such conflicts.
  • We encourage Project maintainers to delegate minute taking responsibilities on a rotating basis to participants in the call, in cases where the scribe is unavailable.
  • The provided minutes will be "raw", and will almost always require further editing by the host and/or attendees of the call to correct domain specific terminology (FinServ and technology acronyms, organisation names, etc.).
  • All meetings where minuting is requested must have a written agenda published prior to the commencement of the call, ideally here on Confluence. Agendas are required by the Foundation's anti-trust policy.