Warning

This page is now hosted on https://odp.finos.org/docs/project-collaboration

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.

Program	GitHub Organization
Hadouken	`https://github.com/HadoukenIO`
Plexus Interop	`https://github.com/finos-plexus`
Symphony	`https://github.com/symphonyoss`

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.

Project Catalog

You can browse all FINOS projects on https://finos.github.io.

Multiple repositores

Each project can have multiple GitHub repositories, which are created during the /wiki/spaces/FINOS/pages/83034172 , or asking support via help@finos.org.

Access Control

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

Checkout the source code
Consume any artifact produced by a Project
Access FINOS issue boards

Any contributor with a GitHub account will be able to:

Use GitHub Issues to contribute to the discussion

Any contributor covered by a /wiki/spaces/FINOS/pages/75530375 can also:

Become a member of the FINOS GitHub Organization (allowing @ mentions on issues and pull requests and simplifying collaboration)
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.

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:

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 tent to have a more thorough validation pipeline

Committers authorized by PMC

GitHub Teams are managed by the Project Lead, but changes must be authorized by the PMC.

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

Who	What
Anyone	Checkout the source code Consume any artifact produced by a Project Access FINOS issue boards
Any GitHub user	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	Become a member of the GitHub FINOS Organization Submit a code change via Pull Request (validated by the FINOS CLA bot)
Committer (GitHub User) and PMC (GitHub User)	Make direct changes to project repositories Anything granted by the `Maintain` permission.
Project Lead (GitHub User)	Request to add new committers to the team (authorized by PMC)
FINOS Team	Administration tasks Monitoring

GitHub member VS FINOS Member

Please note that with FINOS Members we normally refer to the institutions that sit on FINOS board and support us financially, whereas GitHub FINOS Organization members are individuals - represented by a GitHub user(name) - that have a signed CLA with FINOS.

The two concepts are completely unrelated.

How to become a GitHub FINOS Organization member

Assuming that you have read our /wiki/spaces/FINOS/pages/75530375 and have a CLA signed with FINOS, you can request invitation by emailing your GitHub username to help@finos.org.

Committers permissions

Project committers are granted with the Maintain permission on each project (GitHub) repository.

Becoming GitHub FINOS Organization member

Work in progress

Check progress on https://github.com/finos/open-developer-platform/issues/114

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

Sign and submit the FINOS CLA
GitHub account has a verified email address, check github.com/settings/emails
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:

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

Full name
Employer name
GitHub username
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:

Access https://github.com/orgs/finos/people
Search for your name or GitHub username
Open the dropdown close to Private
Select Public visibility

Mentions on GitHub issues

Becoming a member of the GitHub FINOS Organization has the great advantage of allowing @ mentions on Issues and Pull Requests, simplifying collaboration with the rest of the team.

Also, anyone who left a comment on the issue can be engaged as Issue and Pull Request reviewer/assignee.

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:

Extracts the list of GitHub users who contributed to the PR
Matches their identities against FINOS internal identity database
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:

Thank you for your contribution and Welcome to our Open Source Community!

To make sure your pull request is successful, we need all our contributors to be identifiable, but we couldn't parse the GitHub details of the following people : {{unidentifiedUsers}}

Luckily, resolving the issue is straightforward and you can resolve it by following the instructions below.

1. Check your git client is configured with a user email git config --list | grep email

2. If the user email is missing, run the following command, substituting with your git commit email address git config --global user.email email@example.com

3. Make sure your git commit email is configured on GitHub by Setting your Commit Email Address

4. Then, amend the authors in your commit history by using git commit --amend to change your last commit.

Alternatively, use the slightly more complex git reset --soft and git rebase to checkout your changes, rewrite the commit history locally and (force) push changes to the downstream branch.

If you have any issues with the steps above, please email help@finos.org so we can help you resolve before reviewing and accepting your pull request.

Thanks once again for the contribution and understanding.

_cc_ @finos-admin

PR validation failure

If the CLA Bot finds something wrong in a PR, it will fail the validation checks, showing a visible red mark and (optionally, if configured), block anyone to merge the Pull Request.

Re summoning the bot

When a Pull Request gets modified, or a contributors CLA gets added, it can be re-summoned simply adding a comment with the text @finos-cla-bot[bot] check.

GitLab version

There is a GitLab version of this bot that can be found on https://github.com/ScottLogic/gitlab-cla-bot ; FINOS uses it to run an internal GitLab instance.

Teams

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

<FINOS Program Team>
1. <FINOS Project Team, belonging to the Program>
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)

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:

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

Provide a simple way for collaborators to manage their documentation content, using Markdown files and folders within a GitHub repository
Easily enable automated website publication, as soon as content is changed
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:

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.

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

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:

PMC votes for new contributions
Project votes for new committers, releases and other decisions

GitHub Issues can provide an easy platform to vehicle this process:

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

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

Dynamic issue templates

Checkout https://github.com/apps/handlebar-templates if you want to make your meeting issue templates more dynamic and automated

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
Action .github/workflows/meetings.yml defined
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 /wiki/spaces/FINOS/pages/1230176257 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:

a README template, with a suggested structure of content
a NOTICE template, required by FINOS bylaws
a LICENSE template, required by FINOS bylaws
a code of conduct template, required by FINOS bylaws
Contributing guidelines, required by FINOS bylaws
WhiteSource custom configuration, to setup continuous security scanning for your project
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:

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
Edit website/siteConfig.js following comments in file
Install the Docusaurus Build Action provided by FINOS
Make edits on docs/ files and check changes on https://finos.github.io/ name>.

Other resources

Read more about FINOS Community Governance
About permissions on GitHub
About GitHub Teams
Other GitHub guides