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)

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:

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: