finos / finos/architecture-as-code

Establish MAINTAINERS.md

Open
#2,979 2 comments 1 reaction 1 assignee Claimed by @jimthompson5802 View on GitHub
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 14h
Merged PRs (30d)
37

Description

## Feature Proposal

### Target Project:

`finos/architecture-as-code`

This feature applies at the repository level and is intended to provide guidance for maintainers working across the Architecture-as-Code monorepo.

### Description of Feature:

Create a repository-level `MAINTAINERS.md` that provides maintainers with clear, consistent guidance for performing their responsibilities within the Architecture-as-Code project.

The repository currently provides `CONTRIBUTING.md` to help contributors understand how to participate in the project. A complementary `MAINTAINERS.md` would document expectations, practices, and processes that are specific to maintainers.

The goal is to establish a shared reference for how maintainers manage the project, review and merge contributions, make decisions, maintain repository quality, and support contributors.

### User Stories:

As a **new maintainer**, I want documented maintainer guidance so that I can understand my responsibilities and begin performing the role consistently with existing maintainers.

As an **existing maintainer**, I want a shared reference for maintainer practices so that decisions and repository management are consistent across the project.

As a **contributor**, I want maintainer responsibilities and processes to be transparent so that I understand how contributions are reviewed, approved, and merged.

As a **project lead**, I want maintainer practices documented so that knowledge is not dependent on individual maintainers and can be transferred as the maintainer community evolves.

### Current Limitations:

The repository provides contributor-facing guidance through `CONTRIBUTING.md`, but there is no equivalent repository-level document focused specifically on maintainer responsibilities and practices.

As a result, maintainer processes may depend on institutional knowledge, informal communication, or practices learned through experience. This can make onboarding new maintainers more difficult and may lead to inconsistent approaches to repository management.

### Proposed Implementation:

Add a `MAINTAINERS.md` file at the repository root, alongside `CONTRIBUTING.md`, that serves as the primary reference for maintainer-specific guidance.

The document should complement rather than duplicate `CONTRIBUTING.md`. Contributor-facing requirements should remain in `CONTRIBUTING.md`, while `MAINTAINERS.md` should focus on responsibilities and processes performed by maintainers.

Topics should include, where applicable:

* Maintainer roles and responsibilities
* Expectations for reviewing pull requests
* Approval and merge practices
* Issue and pull request triage
* Repository and code quality responsibilities
* CI and required-check expectations
* Release and version-management responsibilities
* Dependency and security-related maintenance
* Decision-making and escalation practices
* Handling breaking or significant architectural changes
* Supporting and interacting with contributors
* Onboarding new maintainers
* References to relevant FINOS or project governance policies

Where existing repository documentation or FINOS policies already define a process, `MAINTAINERS.md` should reference those sources rather than duplicate them.

**Technical design considerations:** This is a documentation-focused feature and should not require changes to runtime components or application architecture.

**API changes:** None.

**Data model changes:** None.

**Dependencies on other components:** None expected. The document may reference existing repository workflows, governance documentation, and FINOS policies.

### Alternatives Considered:

**Continue relying on `CONTRIBUTING.md`.** `CONTRIBUTING.md` is primarily intended for contributors. Expanding it with maintainer-specific procedures could make the document less focused and mix guidance intended for different audiences.

**Document maintainer practices externally.** Maintainer guidance could be maintained in a wiki or other external location, but keeping it within the repository makes the guidance version-controlled, reviewable through the normal pull request process, and discoverable alongside the source code and contributor documentation.

**Rely on informal maintainer knowledge.** Existing maintainers can communicate practices directly to new maintainers, but this does not scale well and creates dependency on institutional knowledge.

### Testing Strategy:

Because this feature introduces documentation rather than executable functionality, testing should focus on validation and review.

The implementation should:

* Pass existing repository documentation, formatting, and link-validation checks.
* Verify that links to repository and FINOS documentation are valid.
* Be reviewed by existing maintainers for accuracy and completeness.
* Confirm that documented processes reflect current repository practices and governance requirements.
* Confirm that the document does not unnecessarily duplicate `CONTRIBUTING.md` or existing governance documentation.

No new unit or integration tests are expected unless repository automation is introduced to validate the document.

### Documentation Requirements:

* Add `MAINTAINERS.md` at the repository root.
* Add an appropriate reference to `MAINTAINERS.md` from `README.md`, `CONTRIBUTING.md`, or another suitable repository navigation point.
* Cross-reference existing contributor, governance, release, security, and development documentation where appropriate.
* Avoid duplicating information already maintained elsewhere when a stable reference can be used instead.

### Implementation Checklist:

* [ ] Design reviewed and approved
* [ ] Implementation completed
* [ ] Tests written and passing
* [ ] Documentation updated
* [ ] Relevant workflows updated (if needed)
* [ ] Performance impact assessed

### Additional Context:

`CONTRIBUTING.md` establishes expectations and guidance for people contributing to the Architecture-as-Code project. This proposal establishes a complementary `MAINTAINERS.md` for the people responsible for reviewing, managing, and maintaining those contributions and the repository itself.

Keeping maintainer guidance in the repository also allows these practices to evolve through the same transparent, version-controlled review process used for other project changes.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.