From 9968356e8e0b04fe87213e5ed2795d6afe65bff1 Mon Sep 17 00:00:00 2001 From: Jeff Darcy Date: Wed, 6 Jan 2016 10:25:16 -0500 Subject: Add accepted/design subdirs, update README to describe them. Also, updated some of the wording and terminology, especially to make the distinction between feature pages and design specs clearer. Signed-off-by: Jeff Darcy Change-Id: I479d30e5ef6d9b278574f3ed80c28f060a6cbe49 Reviewed-on: http://review.gluster.org/13187 Reviewed-by: Niels de Vos Reviewed-by: Venky Shankar Reviewed-by: Shyamsundar Ranganathan Reviewed-by: Kaushal M --- README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 69 insertions(+), 23 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 9a81fa8..33454ec 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,104 @@ Gluster Specs Repository ------------------------ -This is a git repository for doing design review on enhancements to -Gluster. This provides an ability to ensure that everyone -has signed off on the approach to solving a problem early on. +This is a git repository for release planning and design review of enhancements +to Gluster. This provides an ability to ensure that everyone has signed off on +the approach to solving a problem early on. There are two general kinds of +documents here. + + * Feature pages, covering anything that the user or administrator will see + plus planning information (e.g. security or resource impacts). These follow + a fairly rigid template to ensure that all necessary topics are addressed. + + * Design specs, which provide **developer specific** information about the + (actual or proposed) implementation of a feature. These are more free form, + because every feature/project breaks down into different pieces requiring + different emphasis. Because each design is likely to be represented by + multiple documents, either in different formats or to address different + sub-components, design specs should be placed in subdirectories rather than + directly in the ``design`` directory (even if at first there's only one + design document). + +The idea here is that anyone in the community can evaluate, comment on, and +potentially vote on feature pages. Once a feature has been accepted as part of +a release, its feature page is moved into one of the ``accepted`` subdirectories +and its ``design`` subdirectory is created. Repository Structure -------------------- The structure of the repository is as follows:: ``` -. ++-- in_progress/ +| ++-- accepted/ +| +-- release-3.6/ +| +-- release-3.7/ +| +-- done/ -| +-- release-3.4/ -| +-- release-3.5/ | +-- release-3.6/ | +-- release-3.7/ -+-- in_progress/ +| ++-- design/ +| +-- feature_1/ +| +-- feature_2/ ``` -Implemented specs will be moved to ``done`` once the associated code has landed. +Implemented specs will be moved to ``done`` once the associated code has +landed. The Flow of an Idea from your Head to Implementation ---------------------------------------------------- -First propose a spec to the ``in_progress`` directory so that it can be reviewed. Reviewers adding a positive +1/+2 review in gerrit are promising that they will review the code when it is proposed. Spec documents should be approved and merged as soon as possible, and spec documents in the ``in_progress`` directory can be updated as often as needed. Iterate on it. +First propose a feature by adding a page to the ``in_progress`` directory so +that it can be reviewed. Reviewers adding a positive +1/+2 review in gerrit are +promising that they will review the code when it is proposed. Feature pages +should be approved and merged as soon as possible, and feature pages in the +``in_progress`` directory can be updated as often as needed. Iterate on it. -1. Have an idea -2. Propose a spec. -3. Reviewers review the spec. As soon as 2 core reviewers like something, merge it. Iterate on the spec as often as needed, and keep it updated. -4. Once there is agreement on the spec, write the code. -5. As the code changes during review, keep the spec updated as needed. -6. Once the code lands (with all necessary tests and docs), the spec can be moved to the ``done`` directory. If a feature needs a spec, it needs docs, and the docs must land before or with the feature (not after). +1. Have an idea. +2. Propose a feature. +3. Reviewers review the feature page. As soon as 2 core reviewers like + something, merge it. Iterate on the feature page as often as needed, and + keep it updated. +4. Once a feature has been accepted as part of a release - meaning that + resources are available to work on it - move its page to the appropriate + ``accepted`` subdirectory and create a ``design`` subdirectory for it. We + follow an agile(ish) development process, but that's no excuse for failing + to consult others and to do that you need to write something down. +5. Once the design is at least somewhat settled, write code. +6. As issues surface in both the design and the code, update both the feature + page and the design spec(s) as appropriate. +7. Once the code lands (with all necessary tests and docs), the feature page + can be moved to the ``done`` directory. If a feature needs a spec, it needs + docs, and the docs must land before or with the feature (not after). Spec Lifecycle Rules -------------------- -1. Land quickly: A spec is a living document, and lives in the repository not in gerrit. -2. Initial version is an idea not a technical design: That way the merits of the idea can be discussed and landed and not stuck in gerrit limbo land. -3. Second version is an overview of the technical design: This will aid in the technical discussions amongst the community. -4. Subsequent versions improve/enhance technical design: Each of these versions should be relatively small patches to the spec to keep rule #1. And keeps the spec up to date with the progress of the implementation. +1. Land quickly. Both feature pages and design specs are living documents, and + should live live in the repository - not in gerrit. +2. A feature page is supposed to **facilitate** creation of a detailed + description, not to be one already when it's first proposed. That way the + merits of the idea can be discussed and landed and not stuck in gerrit limbo + land. +3. Design specs are not goals in themselves but tools to facilitate technical + discussions within the developer community. How to submit a new feature for review -------------------------------------- 1. Clone this repo -2. Copy the ``template.md`` file in ``in_progress`` directory to ``your_feature.md`` +2. Copy the ``template.md`` file in ``in_progress`` directory to + ``your_feature.md`` 3. Make changes to ``your_feature.md`` 4. Submit changes using ``git-review`` tool. - How to ask questions and get clarifications about a spec -------------------------------------------------------- -To make a comment, suggestion or to ask a question use the gerrit interface like you do for patches on glusterfs project. +To make a comment, suggestion or to ask a question use the gerrit interface +like you do for code patches on glusterfs project. Learn As We Go -------------- -This version of README is largely inspired from openstack-swift project. We can change the process and update this README from our learning and adapt. +This version of README is largely inspired from openstack-swift project. We can +change the process and update this README as we learn and adapt. -- cgit