Software Project Contribution and Onboarding - CALM

[rocketstack-matt]

Please note that only FINOS members can propose new projects. If you're interested in membership, see https://www.finos.org/membership-benefits#become-a-member.

Onboarding Process

Completing an onboarding of a project into FINOS requires following these 5 main steps:

1. Describing the Contribution led by contributor
2. Approval led by FINOS TOC
3. Preparing for Onboarding led by contributor
4. Onboarding completed by FINOS Infra
5. Announcement led by FINOS Marketing

1. Describing The Contribution

This is a list of questions that need to be answered by the contributor in order to allow a new project to pass to the approval stage of onboarding.

Business Problem

Software architecture aims to provide a high-level framework that ensures software systems in highly regulated industries like finance are secure, compliant, and scalable while meeting business objectives. It focuses on creating a structure that supports regulatory compliance, risk management, and adaptability to evolving demands. A strong architecture balances performance, reliability, and maintainability, enabling financial institutions to handle high transaction volumes, ensure operational continuity, and protect sensitive data. By aligning technical design with business goals, architecture facilitates long-term growth and competitiveness.

However, most existing architectural frameworks and tools focus on the initial formation of the architecture, emphasizing planning, governance, and compliance through structured methodologies like TOGAF or Zachman. While these tools provide valuable blueprints, they often operate asynchronously from the development lifecycle (SDLC), relying on manual gating processes and disjointed reviews that delay development and create inefficiencies. They lack tight integration with modern SDLC practices such as Agile, DevOps, and CI/CD, making it challenging to adapt architectural decisions dynamically as systems are implemented. This disconnect limits their effectiveness in delivering seamless, compliant, and adaptable solutions in fast-paced, regulated industries.

Proposed Solution

The Architecture as Code Working Group was formed as part of the FINOS DevOps Automation SIG to focus on trying to define a solution for how we could tightly integrate Software Architecture into the development process. The group was formed in August 2023 and ran regular monthly meet-ups and several offsite workshops with participants from several large financial institutions.

The objective of the working group was to establish a framework for bringing architectures off a whiteboard / Visio diagram and into something machine readable that could be used to provide systematic controls during the SDLC but which would also crucially enable the development of productivity tools which would enable teams to more easily show architectural compliance and thereby reduce or even remove the friction of manual governance processes.

In early 2024 the group started to develop the Common Architecture Language Model (CALM); the framework is a JSON Meta Schema designed to enable system architectures to be capture as code to a high degree of fidelity. The schema is developed as a 'core' schema which provides a generic vocabulary for defining architectures and 'domains' which allow more domain specific concepts to be included and used by those users who have need for them, such as Controls or Business Flows. The use of JSON Schema enables existing tools which are JSON 'aware' such as IDEs to be able to provide additional features such as code completion and validation.

In addition to being able to define specific system architectures, CALM also has the ability to capture architecture patterns. These are codified, reusable architectures which enable a user of CALM to bootstrap their architecture or to compose existing patterns together.

In addition to the CALM schema, the group have also developed an initial set of tools to make it easier to work with CALM and to provide additional capabilities. The core of these additional tools is the Command Line Interface (CLI) which enables uses to generate an architecture from a pattern, validate an architecture or visualize an architecture . We also have a standalone translator to C4 and CalmHub (a distributed artefact repository akin to Maven Central) is in development.

Tentative Roadmap

Describe the short and medium term goals and phases of the project. What does success look like for this project?

Short term (0-6 months)

• Release v1.0 of the CALM specification
• Release v1.0 of the CALM CLI
• Deploy a centrally hosted CalmHub to house the schema and publicly published architecture artefacts
• Publish CalmHub and CLI as Docker images

Medium term (6 - 12 months)

• Introduce static documentation generation capabilities
• Release v1.0 of a CALM interactive visualisation and authoring tool
• Introduce Data representation into CALM
• Introduce CALM to Code observability tools

Current State

Summarize the history and current state of the project CALM already has a repository in the FINOS GitHub organisation and fulfils the requirements and best practices for incubating projects.

CALM Specification The CALM specification has iterated through 7 draft iterations and is nearing finalisation for v1.0 publication

CLI The CLI is feature complete per the four functions mentioned above; it is currently paired to v.2024-04 of the draft schema and is being upgraded to the latest release.

CalmHub is in private development, contribution to the public repository is expect Jan 2025.

Marketing & Communication In addition to the monthly working group and weekly office hours meetings, there have been several offsite workshops and hackdays and CALM has been presented at FINOS OSFF, ScotSoft and the JSON Schema Conference as part of APIDays in Paris.

Existing Materials

If materials already exist, provide a link to them that Foundation staff can access - if it's in a private GitHub.com repositories, you should invite the finos-admin user with R/O permissions to those repositories

• [x] GitHub Repository
  • [x] URL for the repository: https://github.com/finos/architecture-as-code
  • [x] Project Name: Architecture as Code / CALM
  • [x] @finos-admin has been given read-only permissions if private: N/A
• [x] Is Continuous Integration used? Yes, GitHub Actions
• [x] Was the project ever released? Yes, several drafts of the specification are available at https://calm.finos.org/draft/
  • [x] If so, are releases public? Yes
  • [x] And what's the latest released version? https://calm.finos.org/draft/2024-12/meta/core.json
• [x] Existing Project Documentation http://calm.finos.org/
• [x] Does the name have a registered trademark? No
• [x] Is there a logo? No
• [x] High-Level Presentation prepared for Technical Oversight Committee: https://calm.finos.org/talks/
• [x] Are meetings currently held for the project? Yes, monthly Working Group on the 4th Tuesday of each month and weekly office hours for active contributors.
• [x] Are meeting minutes, agenda and attendance tracked? Yes - https://github.com/finos/architecture-as-code/issues?q=+is%3Aissue+label%3Ameeting+

Development Team

Maintainers

Who will be the project maintainer(s)? Provide full name, affiliation, work email address, and GitHub / GitLab username.

Name	Affiliation	Work Email Address	Github / GitLab username
Matthew Bain	Morgan Stanley	[email protected]	@rocketstack-matt
James Gough	Morgan Stanley	[email protected]	@jpgough-ms
Ross Maden	Morgan Stanley	[email protected]	@Thels
Will Osborne	Morgan Stanley	[email protected]	@willosborne
Aiden McPhelim	Morgan Stanley	[email protected]	@aidanm3341
Graham Packer	Morgan Stanley	[email protected]	@grahampacker-ms
Luigi Bulanti	Morgan Stanley	[email protected]	@lbulanti-ms
Leigh Finegold	Morgan Stanley	[email protected]	@LeighFinegold
Denis Coffaro	Morgan Stanley	[email protected]	@dc-ms
Yan Tordoff	Morgan Stanley	[email protected]	@yt-ms
Olivia Johnson	Morgan Stanley	[email protected]	@oliviajanejohns
Matthew Gardner	Morgan Stanley	[email protected]	@matthewgardner

Confirmed contributors

If applicable, list all of the individuals that have expressed interest in and/or are committed to contributing to this project, including full name, affiliation, work email address, and GitHub.com username

Name	Affiliation	Work Email Address	Github / GitLab username
Adwoa-Konadu-Appiah	Turntabl		@Adwoa-Konadu-Appiah
Alex Armstrong	Morgan Stanley	[email protected]	@arhy
David Johnston	RedHat	[email protected]	@djohnston89
Aaman Rebello	Morgan Stanley	[email protected]	@aamanrebello
Oli Bage	LSEG		@ojeb2

Target Contributors

Describe the contributor profile (background, position, organization) you would like to get contributions from. System Architects and developers from Finance or other highly regulated industries who have a need to be able to prove conformance to a governed architecture process.

Other members of FINOS organisations interested in adopting CALM.

Project Communication Channel(s)

• [x] Contributor to ask maintainers which communications channels they'd like to use:
• Asynchronous
  • [x] GitHub Issues (public)
  • [x] GitHub Discussions (public)
  • [x] Mailing-list (groups.io)
  • [x] FINOS Slack Channel (consisting of the above described contributors)
    • [x] General (public) (supply channel name)
• Synchronous
  • [x] Recurring meetings

Understanding FINOS Onboarding Requirements

As a project onboarding into FINOS, you will need to familiarize yourself and your contributor team with the following materials:

• FINOS overview (if necessary)
• FINOS Maintainers cheatsheet
• FINOS Project/Standards Governance
• FINOS Project Lifecycle

Record The Contribution (FINOS Infra)

• [x] Submit contribution to LF via PCC

2. Approval

The FINOS Technical Oversight Committee (TOC) is responsible for approving FINOS project contributions; feel free to check their contribution principles.

If needed, the TOC will request a follow up either via GitHub Issue comments or by inviting project leads to one of their recurrent meetings.

Tasks (for FINOS Infra/TOC)

• [x] Prioritise this issue on the TOC Backlog
• [x] Assign this issue to @eddie-knight
• [x] Add the ready-for-tsc label
• [x] TOC to invite contributors to present their project
• [x] FINOS TOC approves/rejects the contribution
• [x] Ask @jgavronsky to mark contribution as "Engaged" within LF systems
• [x] Update the contribution status to "Engaged" in PCC

TOC Findings / Report

TOC to enter findings summary here.

3. Preparing For Onboarding

Before the FINOS team can onboard your project, there are a few housekeeping that need to be taken care of. These must be completed by the contributor, with help if required from the FINOS Infra.

Kick-off meeting (N/A)

• [x] Set up kick-off meeting with project leads
• [x] Run kick-off meeting
  • [x] Walk through the checklist in part 1, ensure all the questions are answered and remove items that don't apply
  • [x] Write and send contribution proposal announcement (optional - see below)

Proposal (Lead Maintainer) (N/A)

• [x] Lead maintainer to send out announcement to [email protected] using this template:

  Dear FINOS Community, 
  
  We would like to propose a new FINOS project. Please review the proposal details at (_TODO: add link to the GitHub issue proposal_).
  
  If you're interested in participating, please :+1: the GitHub issue proposal and drop a comment with your name, org and email
  
  Thanks a lot,
  

Logo / Trademarks

• [x] Sign the project contribution agreement to allow FINOS to act on behalf of the contributor for accounts related to the project (e.g., GitHub, domain names, social media) and to optionally manage trademark assignment (N/A)
• [x] Request logo design from [email protected] (if needed)
• [x] The codebase doesn’t include any patent or copyright that conflicts with FINOS Governance and bylaws. (Infra team to validate with FINOS Legal team if anything important is raised)

FINOS Project Blueprint

• [x] finos-admin is Admin of the GitHub repository to transfer
• [x] Apply project blueprint contents - see our docs on collaboration infrastructure
  • [x] README.md file contains the sections in the README Template
  • [x] Project FINOS badge in README (incubating)
  • [x] OpenSSF Passing Badge
  • [x] License in README
  • [x] Contributing in README
  • [x] CONTRIBUTING.md
  • [x] LICENSE (replace {} placeholders)
  • [x] Ensure that the proper project governance is in the CONTRIBUTING.md file
• [x] All incubating criteria are checked and documented below

Add documentation here

4. FINOS Onboarding

This is performed by FINOS Infra once the three previous stages are complete, with support from the contributor and the FINOS Infra team.

Maintainers, Contributors and CLAs

• [x] Identify other existing contributors (assuming there's a contribution history (eg Git history)
• [x] Check if maintainers and other contributors are all covered by FINOS CLA
• [x] Engage with FINOS Legal team to figure out what’s needed to cover all maintainers and contributors with FINOS CLA
• [x] Reach out to contributors and employers to coordinate CLA signatures
• [x] Invite GitHub usernames to GitHub FINOS Org
• [x] Create <project-name>-maintainers GitHub team and invite users

Validation (only if code is contributed)

• [x] Backup (even with screenshot) GitHub permissions of the repository to transfer
• [x] Check GitHub repository transfer requirements:
  • [x] finos-admin has Admin to all repositories to transfer
  • [x] finos-admin ia allowed to transfer repositories out of the org
  • [x] if the repository is owned by a user (and not an org), the user must be able to transfer the repository to finos-admin
• [ ] The codebase doesn’t have HIGH or CRITICAL CVEs across direct and transitive libraries
• [x] The codebase doesn’t have any unfriendly licenses across direct and transitive libraries
• [x] (optional - if a build system is provided) The build process runs successfully
• [x] The codebase doesn’t include any patent or copyright that conflicts with FINOS Governance and bylaws (to be validated with FINOS Legal team)
• [ ] All incubating criteria are met (review documentation provided above)

Code transfer

• [x] Transfer all code assets as GitHub repositories under github.com/finos
• [x] Rename main branch to main (instead of master)
• [x] Configure finos-admins (Maintain role) and finos-staff (Triage role) team permissions

Project Communication Channel(s)

• [x] Create the identified communication channels during infra set up
• [x] Create mailing-list on lists.finos.org (if requested)
  • [ ] Enable Hubspot Sync for all project mailing lists created
  • [ ] Aggregate mailing lists to [email protected]
  • [ ] Update marketing lists (see Email List and Email filter fields), particularly Hubspot all community list
• [x] Create Slack channels if requested.
• [x] Link communication channels linked front-and-center in the project README.md

Repository setup

• [x] Enable EasyCLA
• [x] Add identities, orgs and affiliations to metadata (deprecated by EasyCLA)
• [ ] Add logo to FINOS landscape
  • [ ] Create staging branch on finos/finos-landscape
  • [ ] Merge finos/metadata changes on master (will udpdate landscape.yml in finos/finos-landscape)
  • [ ] Create PR from staging branch on finos/finos-landscape
  • [ ] Review Netlify preview
  • [ ] Merge PR
• [x] Add project maintainers emails to [email protected] list
• [x] Add project maintainers GitHub usernames to the project-maintainers Team
• [ ] (best effort) Update release coordinates and code namespace to include finos
• [x] Check that CVE (and preferably static code analysis, if applicable) scanning is in place
• [x] Enable automated dependency update, using Renovate
• [x] Enable branch protection (Require a pull request before merging)

5. Announcement

(Lead: Project Lead and FINOS Infra team)

• [ ] Update the contribution status to "Active" by sending another email to LF Legal Representative with the name of the project and its new status.
• [ ] Lead maintainer works with FINOS marketing to send out announcement to [email protected] , checkout announcement template at the Contribution page
• [ ] Notify FINOS marketing (@grizzwolf + finos-marketing internal Slack channel)

[eddie-knight]

@jgavronsky The TOC has voted today to accept CALM as an incubating project.

[mindthegab]

Thank you @eddie-knight and @finos/toc! Super exciting project. @TheJuanAndOnly99 will commence onboarding and @opoupeney will help with dissemination!

[mindthegab]

@TheJuanAndOnly99 @opoupeney is this complete? I see some checklist items still open but the bulk seems done - would love to make some noise here, so please can we fast track this if possible and handover to marketing as well?

Thanks!

[TheJuanAndOnly99]

@mindthegab apologies for the delayed update we're working with @rocketstack-matt and the FINOS marketing team to send out an announcement to [email protected] and looking at other marketing opportunities.

[TheJuanAndOnly99]

Congratulations @rocketstack-matt + team, thank you for your contributions to FINOS!

Contribution announcement can be found here