diff --git a/docs/source/design/README.md b/docs/source/design/README.md new file mode 100644 index 0000000000..94161e68bc --- /dev/null +++ b/docs/source/design/README.md @@ -0,0 +1,40 @@ +![Corda](https://www.corda.net/wp-content/uploads/2016/11/fg005_corda_b.png) + + + +# Design Documentation + +This directory should be used to version control Corda design documents. + +These should be written in [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) (a design template is provided for general guidance) and follow the design review process outlined below. It is recommended you use a Markdown editor such as [Typora](https://typora.io/), or an appropriate plugin for your favourite editor (eg. [Sublime Markdown editing theme](http://plaintext-productivity.net/2-04-how-to-set-up-sublime-text-for-markdown-editing.html)). + +## Design Review Process + +Please see the [design review process](./designReviewProcess.md). + +* Feature request submission +* High level design +* Review / approve gate +* Technical design +* Review / approve gate +* Plan, prototype, implement, QA + +## Design Template + +Please copy this [directory](./designTemplate) to a new location under `/docs/source/design` (use a meaningful short descriptive directory name) and use the [Design Template](./designTemplate/design.md) contained within to guide writing your Design Proposal. Whilst the section headings may be treated as placeholders for guidance, you are expected to be able to answer any questions related to pertinent section headings (where relevant to your design) at the design review stage. Use the [Design Decision Template](./designTemplate/decisions/decision.md) (as many times as needed) to record the pros and cons, and justification of any design decision recommendations where multiple options are available. These should be directly referenced from the *Design Decisions* section of the main design document. + +The design document may be completed in one or two iterations, by completing the following main two sections individually or singularly: + +* High level design + Where a feature requirement is specified at a high level, and multiple design solutions are possible, this section should be completed and circulated for review prior to completing the detailed technical design. + High level designs will often benefit from a formal meeting and discussion review amongst stakeholders to reach consensus on the preferred way to proceed. The design author will then incorporate all meeting outcome decisions back into a revision for final GitHub PR approval. +* Technical design + The technical design will consist of implementation specific details which require a deeper understanding of the Corda software stack, such as public API's and services, libraries, and associated middleware infrastructure (messaging,security, database persistence, serialization) used to realize these. + Technical designs should lead directly to a GitHub PR review process. + +Once a design is approved using the GitHub PR process, please commit the PR to the GitHub repository with a meaningful version identifier (eg. my super design document - **V1.0**) + +## Design Repository + +All design documents will be version controlled under github under the directory `/docs/source/design`. +For designs that relate to Enterprise-only features (and that may contain proprietary IP), these should be stored under the [Enterprise Github repository](https://github.com/corda/enterprise). All other public designs should be stored under the [Open Source Github repository](https://github.com/corda/corda). diff --git a/docs/source/design/designReviewProcess.md b/docs/source/design/designReviewProcess.md new file mode 100644 index 0000000000..57cc17b5b3 --- /dev/null +++ b/docs/source/design/designReviewProcess.md @@ -0,0 +1,106 @@ + +# Overview + +The Corda Design Review process defines a means of editing, storing, collaborating, reviewing and approving Corda documentation in a consistent, structured, easily accessible and open manner. + +# Background + +Historically, Corda design documentation has been produced in an ad hoc fashion to include: +* Multiple sources and formats of storage + * Internal ([Tech/Arch technical discussion](https://r3-cev.atlassian.net/wiki/spaces/AR/pages/2588746/Internal+Technical+Discussion)) and External ([AWG design documents](https://r3-cev.atlassian.net/wiki/spaces/AWG/pages/56623418/Design+Documents)) facing wiki(s) + * [Public github wiki](https://github.com/corda/corda/wiki) + * [Discourse posts](https://discourse.corda.net/c/corda-discussion) +* Multiple authored versions of same design with differing coverage + * Elaboration and/or additions to scope + * Differing opinions, proposals, suggestions. +* Unstructured prose (no consistency in format and structure) +* Lack of versioning (wiki documents typically evolve without versioned references) +* Lack of traceability (audit) to original requirement(s) +* Undefined review and approval process, leading to misunderstandings and open interpretations at time of implementation by platform development team +* Lack of proposed implementation plan (time, resources, effort). +* Often missing stakeholder collaboration and review in the feedback cycle. + +# Process + +This process specifies: + +1. Usage of a design template to include: + * Versioning: design documents can be referenced at a point in time, and evolve from such. + * Review and approval history: incorporating relevant stakeholders from R3 (Platform, Product Management, Services) and + other relevant review groups (community, partners, customers, key collaborators) as deemed appropriate to the request. Ensure design + meets the requirements and is realizable within a proposed implementation timeframe. + * Consistent structure and headings: top level headings should be preserved, second level headings provide guidance on + content to include, and may be omitted where not relevant. + * The design template includes both High Level (conceptual, logical) and Technical (implementation specific) sections. + * Design decisions are clearly identified with pros/cons of proposed options, and agreed recommendation. + +2. Document review and approval by relevant stakeholders and impacted parties to include R3 organisational units, such as Platform Engineering, Product Management and Services (where relevant), and key stakeholders, to include customers, partners, key collaborators, and community leaders. + * Product owner (originator of requirements) + * Design Approval Board (DAB) + * Platform Development technical lead (and/or nominated developer(s)) + * Project Technical Lead / Solution Architect (if originating from an R3 Technical Services project) + * Other identified stakeholders (community leaders, partners, customers, key collaborators) + +3. Planning: allocation to Corda (open source) or Enterprise project JIRA epic(s) (and/or set of stories) and prioritisation within Product Backlog for future implementation within a Development Team Sprint. + +4. Document repository locations, according to whether the design is related to Open Source or Enterprise (internal only). + The recommended repository source is GitHub, and documents should be stored in [Markdown](https://en.wikipedia.org/wiki/Markdown). + The collaboration and review process should follow the standard [GitHub Pull Request](https://confluence.atlassian.com/bitbucket/work-with-pull-requests-223220593.html) mechanism. + * [Enterprise Github repository](https://github.com/corda/enterprise) + * [Open Source Github repository](https://github.com/corda/corda) + +The following diagram illustrates the process flow: + +![Design Review Process](./designReviewProcess.png) + +# Review Groups +Design documents should include all relevant stakeholders in their distribution (mostly as PR reviewers in github). This will often vary and depend on the origin of the Feature Request, particularly for high level business requirements. Technical Design Documents will tend to include a small set of stakeholders (Design Approval Board, Platform Development, DevOps). Final approval authority lays with at least one member of the Design Approval Board (DAB) or nominated delegate(s). + +Design Approval Board (DAB) +* Richard G Brown (CTO) +* James Carlyle (Chief Engineer) +* Mike Hearn (Lead Platform Engineer) +* Mark Oldfield (Lead Platform Architect) +* Jonathan Sartin (Information Security manager) +* Select external key contributors (directly involved in design process) + +Other review groups inlcude: + +* Product Management + +* Developer Relations + +* Platform Development Team Leads + + (may nominate team members as design leads) + +* DevOps + +* Services – Project (Incubation & Acceleration) + + * Nominated project leads + + Services – Technical (Consulting) + * Nominated solution architects + +* External + + * AWG (general) + * Consortium members + * ISV, SI, Partners + * Customers + * Key collaborators + +# Applicability and Timing + +This process should be applied to any major feature request gathered by the product management team or lead technologists that has been entered in the product backlog as a requirement, and has been prioritized for imminent execution. + +Publication and distribution of a design document from initial review to full approval will vary on a case by case basis. + +In general, + * High Level designs may require a longer approval cycle as they may need to host a formal review meeting with the DAB in attendance, + and will typically have larger stakeholder audiences (potentially including external reviewers), thus leading to multiple iterations of revision. + In either case the High Level design must be raised as a GitHub PR and obtain formal approval by reviewers. + * Technical designs are anticipated to go through a shorter cycle, with immediate feedback via the GitHub PR workflow. + Once approved, a Technical Design should be decomposed into a set of implementable Epic/Stories for prioritization and + scheduling as part of Development team(s) delivery cycle(s). diff --git a/docs/source/design/designReviewProcess.png b/docs/source/design/designReviewProcess.png new file mode 100644 index 0000000000..c694eea221 Binary files /dev/null and b/docs/source/design/designReviewProcess.png differ diff --git a/docs/source/design/designTemplate/decisions/decision.md b/docs/source/design/designTemplate/decisions/decision.md new file mode 100644 index 0000000000..9a2ca69069 --- /dev/null +++ b/docs/source/design/designTemplate/decisions/decision.md @@ -0,0 +1,39 @@ +![Corda](https://www.corda.net/wp-content/uploads/2016/11/fg005_corda_b.png) + +-------------------------------------------- +Design Decision: +============================================ + +## Background / Context + +Short outline of decision point. + +## Options Analysis + +### A.