Code in the Foundation is hosted exclusively on https://github.com/finos, with exception for Hadouken, Plexus Interop and Symphony programs, 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.

On top of code hosting, GitHub.com provides a full suite of collaboration tools, which seamlessly integrate into source code, sometimes that is referred to as GitOps.

Access Control

Because all repositories managed by the Foundation are open (public), anyone is able to:

1. Checkout the source code

2. Consume any artifact produced by a Project

3. Access FINOS issue boards

Any contributor with a GitHub account will be able to:

1. Use GitHub Issues to contribute to the discussion

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

1. Become a member of the FINOS GitHub Organization (allowing @ mentions on issues and pull requests and simplifying collaboration)

2. Submit a code change via Pull Request; the FINOS CLA bot scans every Pull Request to check that FINOS has a CLA on file for each contributor

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.

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

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

  • GitHub forces you to set the email address as public, or it would reject push operations with push declined due to email privacy restrictions

Actors and permissions

Becoming GitHub FINOS Organization member

In order to become part of the GitHub FINOS Org and become member of some project teams, we require to:

1. Sign and submit the FINOS CLA

2. GitHub account has a verified email address, check github.com/settings/emails

3. Set user.email - on Git client(s) used to push code to github.com/finos repositories - with the email address validated on step #2

We also suggest to:

1. Set email address is the corporate one, as it simplifies affiliation tracking on our side

If all requirements are in place, you can request invitation to FINOS GitHub Organization by emailing help@finos.org with

1. Full name

2. Employer name

3. GitHub username

4. Corporate email address.

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.

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

Open

CLA bot

To help project leads validating external contributor's identity and capacity to contribute code to the Foundation, the Foundation team have deployed an instance of cla-bot, which validates all Pull Requests (PRs) across all FINOS repositories and:

1. Extracts the list of GitHub users who contributed to the PR

2. Matches their identities against FINOS internal identity database

3. Updates the Pull Request with the result of the validation

   1. If ok, adds a cla-signed label

   2. if not ok, posts a comment on the issue and informs 1) the user on how to submit the CLA to FINOS 2) the project lead that the PR cannot be merged.

The CLA bot source code can be found on https://github.com/finos/cla-bot.

Email validation

In order to allow the CLA bot to validate a Pull Request, every contributor must ensure that commits are signed with a valid email address, properly configured (and verified) on GitHub. Otherwise, the CLA bot will post the following message:

Teams

Every Program, PMC and Project will be mapped as a GitHub team, following a 2-levels hierarchical structure:

1. <FINOS Program Team>

   1. <FINOS Project Team, belonging to the Program>

2. panpmcs

   1. <FINOS PMC team>

Note that FINOS Program Teams only inherit members from sub-groups, they are not directly managed.

Each repository will grant access to these teams, as shown in the picture below (taken from the datahelix project)

Open

Other use cases

Issues

GitHub Issues provide 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

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

1. Provide a simple way for collaborators to manage their documentation content, using Markdown files and folders within a GitHub repository

2. Easily enable automated website publication, as soon as content is changed

3. Allow FINOS to enforce graphic guidelines across all websites

Checkout  FDC3 and Financial Objects as examples; you can also read more on how FINOS uses Docusaurus.

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.

Voting

FINOS Governance processes require voting at different levels (and publicly available), including but not limited to:

1. PMC votes for new contributions

2. Project votes for new committers, releases and 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:

   1. Title and description of the vote; use the [VOTE] prefix in the issue title, to help issue browsing and discoverability

   2. Add the vote label

   3. list of users who have the right to a binding vote, typically the project or PMC teams

2. Everyone can vote the issue, until the vote is open:

   1. Those with a GitHub account can simply react to the issue (see image to the right)

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

   1. Total votes (add links to email web history for each email vote, if any)

   2. Binding votes (Approve, Deny, Abstained)

   3. 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 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. Also the meeting leader must comment 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. 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

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

1. a README 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