diff options
Diffstat (limited to 'doc/architecture/blueprints/_template.md')
-rw-r--r-- | doc/architecture/blueprints/_template.md | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/doc/architecture/blueprints/_template.md b/doc/architecture/blueprints/_template.md new file mode 100644 index 00000000000..e99ce61970a --- /dev/null +++ b/doc/architecture/blueprints/_template.md @@ -0,0 +1,142 @@ +--- +status: proposed +creation-date: yyyy-mm-dd +authors: [ "@username" ] +coach: "@username" +owning-section: "~section::<section>" +participating-sections: [] +approvers: [ "@product-manager", "@engineering-manager" ] +--- + +<!-- +**Note:** Please remove comment blocks for sections you've filled in. +When your blueprint is complete, all of these comment blocks should be removed. + +To get started with a blueprint you can use this template to inform you about +what you may want to document in it at the beginning. This content will change +/ evolve as you move forward with the proposal. You are not constrained by the +content in this template. If you have a good idea about what should be in your +blueprint, you can ignore the template, but if you don't know yet what should +be in it, this template might be handy. + +- **Fill out this file as best you can.** At minimum, you should fill in the + "Summary", and "Motivation" sections. These can be brief and may be a copy + of issue or epic descriptions if the initiative is already on Product's + roadmap. +- **Create a MR for this blueprint.** Assign it to an Architecture Evolution + Coach (i.e. a Principal+ engineer). +- **Merge early and iterate.** Avoid getting hung up on specific details and + instead aim to get the goals of the blueprint clarified and merged quickly. + The best way to do this is to just start with the high-level sections and fill + out details incrementally in subsequent MRs. + +Just because a blueprint is merged does not mean it is complete or approved. +Any blueprint is a working document and subject to change at any time. + +When editing blueprints, aim for tightly-scoped, single-topic MRs to keep +discussions focused. If you disagree with what is already in a document, open a +new MR with suggested changes. + +If there are new details that belong in the blueprint, edit the blueprint. Once +a feature has become "implemented", major changes should get new blueprints. + +The canonical place for the latest set of instructions (and the likely source +of this file) is [here](/doc/architecture/blueprints/_template.md). +--> + +# {+ Title of Blueprint +} + +<!-- +This is the title of your blueprint. Keep it short, simple, and descriptive. A +good title can help communicate what the blueprint is and should be considered +as part of any review. +--> + +[[_TOC_]] + +## Summary + +<!-- +This section is very important, because very often it is the only section that +will be read by team members. We sometimes call it an "Executive summary", +because executives usually don't have time to read entire document like this. +Focus on writing this section in a way that anyone can understand what is says, +the audience here is everyone: executives, product managers, engineers, wider +community members. + +A good summary is probably at least a paragraph in length. +--> + +## Motivation + +<!-- +This section is for explicitly listing the motivation, goals and non-goals of +this blueprint. Describe why the change is important, all the opportunities, +and the benefits to users. + +The motivation section can optionally provide links to issues that demonstrate +interest in a blueprint within the wider GitLab community. Links to +documentation for competing products and services is also encouraged in cases +where they demonstrate clear gaps in the functionality GitLab provides. + +For concrete proposals we recommend laying out goals and non-goals explicitly, +but this section may be framed in terms of problem statements, challenges, or +opportunities. The latter may be a more suitable framework in cases where the +problem is not well-defined or design details not yet established. +--> + +### Goals + +<!-- +List the specific goals / opportunities of the blueprint. + +- What is it trying to achieve? +- How will we know that this has succeeded? +- What are other less tangible opportunities here? +--> + +### Non-Goals + +<!-- +Listing non-goals helps to focus discussion and make progress. This section is +optional. + +- What is out of scope for this blueprint? +--> + +## Proposal + +<!-- +This is where we get down to the specifics of what the proposal actually is, +but keep it simple! This should have enough detail that reviewers can +understand exactly what you're proposing, but should not include things like +API designs or implementation. The "Design Details" section below is for the +real nitty-gritty. +--> + +## Design and implementation details + +<!-- +This section should contain enough information that the specifics of your +change are understandable. This may include API specs (though not always +required) or even code snippets. If there's any ambiguity about HOW your +proposal will be implemented, this is the place to discuss them. + +If you are not sure how many implementation details you should include in the +blueprint, the rule of thumb here is to provide enough context for people to +understand the proposal. As you move forward with the implementation, you may +need to add more implementation details to the blueprint, as those may become +an important context for important technical decisions made along the way. A +blueprint is also a register of such technical decisions. If a technical +decision requires additional context before it can be made, you probably should +document this context in a blueprint. If it is a small technical decision that +can be made in a merge request by an author and a maintainer, you probably do +not need to document it here. The impact a technical decision will have is +another helpful information - if a technical decision is very impactful, +documenting it, along with associated implementation details, is advisable. + +If it's helpful to include workflow diagrams or any other related images. +Diagrams authored in GitLab flavored markdown are preferred. In cases where +that is not feasible, images should be placed under `images/` in the same +directory as the `index.md` for the proposal. +--> |