Skip to main content

0021: Contribution and Proposal Management Strategy

Date: 2025-08-13

Status: Proposed

Context​

As the Citadel project grows, it will receive feature requests, bug reports, and architectural suggestions from a wide range of contributors, including the open-source community and stakeholders representing paying customers. We need a clear, transparent, and structured process for managing these contributions to ensure that all ideas are evaluated fairly and that development efforts align with the project's strategic goals and architectural principles.

Decision​

We will adopt a formal, structured process for managing all contributions. This process makes a clear distinction between bug reports and new feature proposals.

  1. Bug Reports (GitLab Issues)

    • The GitLab issue tracker is to be used exclusively for reporting verifiable bugs in the existing software.
    • Feature requests or general discussions submitted as issues will be closed with a request to follow the formal proposal process.

  2. Feature Proposals (Citadel Enhancement Proposal - CEP)

    • Entry Point: The sole entry point for any new feature or significant change is a Citadel Enhancement Proposal (CEP).
    • Process:
      1. A contributor creates a new CEP document from a template in a dedicated feature branch (e.g., cep/add-saml-support).
      2. The CEP must be detailed enough for a human or AI to begin implementation. It must clearly define the problem, the proposed solution, user stories, and technical requirements.
      3. The contributor opens a Merge Request (MR) to merge the CEP into the main branch.
    • Discussion & Review: The MR itself serves as the formal forum for discussion and review. This keeps the discussion tied directly to the proposed change.
    • Decision:
      • Acceptance: Merging the MR into main signifies that the CEP is Accepted. The proposal is now part of the official project documentation.
      • Rejection/Deferral: Closing the MR without merging signifies that the proposal is Rejected or Deferred. The history remains in the closed MR for future reference.

  3. Architectural Design (ADR)

    • Trigger: An Accepted CEP that requires a significant architectural change, introduces a new service, or modifies a core cross-cutting concern must be accompanied by a new ADR.
    • Relationship: The CEP defines the problem, while the ADR defines the architectural solution ("how").

  4. Implementation (Checklist)

    • Trigger: Once a CEP is Accepted and any required ADRs are approved, the work is broken down into a detailed implementation checklist.
    • Process: The checklist is added to the project backlog and development can begin, following the project's TDD and layered architecture principles.

Consequences​

Positive​

  • Clarity & Focus: The main branch contains only accepted proposals and working code, providing a clean context for developers and AI assistants.
  • Quality: Ensures that ideas are thoroughly vetted and designed before implementation begins.
  • Prioritization: Creates a formal mechanism for prioritizing work based on both community interest and business needs.
  • Traceability: The MR serves as a permanent, auditable record of the discussion and decision-making process for each proposal.

Negative​

  • Process Overhead: This formal process introduces more steps than an informal "just do it" approach. This is a deliberate trade-off in favor of long-term quality and maintainability.

This ADR formalizes the governance model for how ideas become reality within the Citadel project. It prioritizes a clean development history and rigorous, transparent decision-making.