From d514ff8cd44bc157ef181551d8ac14b24cb34ffd Mon Sep 17 00:00:00 2001 From: Yih Leong Sun Date: Fri, 7 Apr 2017 22:33:41 +0000 Subject: [PATCH] Rename user-story to development proposal. As discussed in PWG Milan meeting, rephrasing user-story to development proposal. Also making changes to each section as mandatory or N/A. And added description to each section. Change-Id: I7f516a7e6151f391446369564aca9aee24c3bfce --- development-proposal-template.rst | 192 ++++++++++++++++++++++++++++++ user-story-template.rst | 180 ---------------------------- 2 files changed, 192 insertions(+), 180 deletions(-) create mode 100644 development-proposal-template.rst delete mode 100644 user-story-template.rst diff --git a/development-proposal-template.rst b/development-proposal-template.rst new file mode 100644 index 0000000..a3aed00 --- /dev/null +++ b/development-proposal-template.rst @@ -0,0 +1,192 @@ +.. This template should be in ReSTructured text. Please do not delete any of +.. the sections in this template. If you have nothing to say for a whole +.. section, just write: None. For help with syntax, see +.. http://sphinx-doc.org/rest.html You can also use an online RST editor at +.. rst.ninjs.org to generate proper RST. + + +The title of Development Proposal +================================= +.. In order to propose submitting a Development Proposal as a cross project +.. spec replace 'Cross Project Spec - None' with +.. 'Cross Project Spec - Ready for Submission', +.. after this change is accepted and merged then submit the Cross Project Spec +.. to the openstack/openstack-specs repository and replace 'Ready for +.. Submission' with a link to the review. After the Cross Project Spec is +.. merged, update this entry with the link to the spec as in +.. 'Cross Project Spec - '. +.. Before proposing be sure to create and provide a link to the +.. Feature Tracker. + +Cross Project Spec - None + +Feature Tracker - None + +Problem Overview +---------------- +.. This section is mandatory. +.. Please use it to provide a detailed description of the problem that this +.. Development Proposal is trying to address. This should include the types of +.. functions that you expect to run on OpenStack and their interactions +.. both with OpenStack and with external systems. + +Mandatory section. See rst comment in this document. + +Opportunity/Justification +------------------------- +.. This section is mandatory. +.. Use this section to give opportunity details that support why +.. pursuing this development proposal would help address key barriers to +.. adoption or operation. + +.. Some examples of information that might be included here are applicable +.. market segments, workloads, user bases, etc. and any associated data, +.. and any impact if such proposal/feature is not supported. + +Mandatory section. See rst comment in this document. + +Requirement Specification +------------------------- + +Use Cases ++++++++++ +.. This section is mandatory. You may submit multiple use cases in a single +.. submission as long as they are inter-related and can be associated with a +.. single epic and/or function. If the use cases are explaining goals that +.. fall under different epics/themes then please complete a separate submission +.. for each group of use cases. + +.. Please provide a unique three character reference and three digit number for +.. each use case. +.. For example, CRM001, CRM002, etc, for use cases of Capacity Management. + +.. Please describe as a list of use cases targeted at OpenStack UX Personas, +.. ideally in this or a similar format: +.. * XXX### As ``_, I want to so that + +Mandatory section. See rst comment in this document. + +This section utilizes the `OpenStack UX Personas`_. + +.. _OpenStack UX Personas: http://docs.openstack.org/contributor-guide/ux-ui-guidelines/ux-personas.html +.. _: http://docs.openstack.org/contributor-guide/ux-ui-guidelines/ux-personas/ + +Usage Scenario Examples ++++++++++++++++++++++++ +.. This section is mandatory. +.. In order to explain your use cases, if possible, provide an example in the +.. form of a scenario to show how the specified user type might interact with the +.. use case and what they might expect. An example of a usage scenario can be +.. found at http://agilemodeling.com/artifacts/usageScenario.htm of a currently +.. implemented or documented planned solution. + +.. If you have multiple usage scenarios/examples (the more the merrier) you may +.. want to use a numbered list with a title for each one, like the following: + +.. 1. Usage Scenario Title +.. i. 1st Step +.. ii. 2nd Step +.. 2. Usage Scenario Title +.. i. 1st Step +.. ii. 2nd Step +.. [...] + +Mandatory section. See rst comment in this document. + +Acceptance Criteria ++++++++++++++++++++ +.. This section is mandatory +.. In order to define completed implementation of a development proposal, +.. provide detailed definitions of acceptance criteria for this proposal. +.. This should include where applicable the specific project set appropriate, +.. the user focused experience and in some cases references to types of +.. specific artifacts. + +.. Please reference the use cases by three character and three number +.. references defined above. + +.. Ex. CRM001 - All Interop Projects obtain tag "FOO" + +Mandatory section. See rst comment in this document. + +Related Development Proposals ++++++++++++++++++++++++++++++ +.. If there are related Development Proposals that have some overlap in the +.. problem domain or that you perceive may partially share requirements or a +.. solution, reference them here. +.. N/A if there is none. + +N/A. + +Requirements +++++++++++++ +.. It might be useful to specify additional requirements that should be +.. considered but may not be apparent through the use cases and usage examples. +.. This information will help the development be aware of any additional known +.. constraints that need to be met for adoption of the newly implemented +.. features/functionality. + +.. Use this section to define the functions that must be available or any +.. specific technical requirements that exist in order to successfully support +.. your use case. If there are requirements that are external to OpenStack, +.. include them as such. + +.. Please always add a comprehensible description to ensure that people +.. understand your need. + +.. * 1st Requirement +.. * 2nd Requirement +.. * [...] + +.. N/A if there is none. + +N/A. + +External References ++++++++++++++++++++ +.. Please use this section to add references for standards or well-defined +.. mechanisms. You can also use this section to reference existing +.. functionality that fits the Development Proposal outside of OpenStack. + +.. If any of your requirements specifically call for the implementation of a +.. standard or protocol or other well-defined mechanism, +.. use this section to list them. + +.. N/A if there is none. + +N/A. + +Rejected Proposals +------------------ +.. Please fill out this section after a Development Proposal has been submitted +.. as a cross project spec to highlight any proposal deemed out of scope of the +.. relevant cross project spec. + +.. N/A if there is none. + +N/A. + +Glossary +-------- +.. It is highly suggested that you define any terms, abbreviations that are not +.. commonly used in order to ensure that your Development Proposal is +.. understood properly. + +.. Provide a list of acronyms, their expansions, and what they actually mean in +.. general language here. Define any terms that are specific to your problem +.. domain. If there are devices, appliances, or software stacks that you expect +.. to interact with OpenStack, list them here. + +.. Remember: OpenStack is used for a large number of deployments, and the better +.. you communicate your Development Proposal, the more likely it is to be +.. considered by the community. + +.. Examples: +.. **reST** reStructuredText is a simple markup language +.. **TLA** Three-Letter Abbreviation is an abbreviation consisting of three +.. letters +.. **xyz** Another example abbreviation + +.. N/A if there is none. + +N/A. diff --git a/user-story-template.rst b/user-story-template.rst deleted file mode 100644 index d654385..0000000 --- a/user-story-template.rst +++ /dev/null @@ -1,180 +0,0 @@ -.. This template should be in ReSTructured text. Please do not delete any of -.. the sections in this template. If you have nothing to say for a whole -.. section, just write: None. For help with syntax, see -.. http://sphinx-doc.org/rest.html You can also use an online RST editor at -.. rst.ninjs.org to generate proper RST. - - -The title of your use case -========================== -**Sections in** *italics* **are optional.** - -.. In order to propose submitting a User Story as a cross project spec replace -.. 'Cross Project Spec - None' with 'Cross Project Spec - Ready for Submission' -.. after this change is accepted and merged then submit the Cross Project Spec -.. to the openstack/openstack-specs repository and replace 'Ready for -.. Submission' with a link to the review, and after merger of the Cross Project -.. spec with a link to the spec. Before proposing be sure to create and provide -.. a link to the User Story Tracker - -Cross Project Spec - None - -User Story Tracker - None - -Problem description -------------------- - -*Problem Definition* -++++++++++++++++++++ -.. This section is optional. -.. Please use it to provide additional details (if available) about your user story -.. (if warranted) for further expansion for clarity. A detailed description of the -.. problem. This should include the types of functions that you expect to run on -.. OpenStack and their interactions both with OpenStack and with external systems. -.. Please replace "None." with the problem description if you plan to use this -.. section. - -None. - -Opportunity/Justification -+++++++++++++++++++++++++ -.. This section is mandatory. -.. Use this section to give opportunity details that support why -.. pursuing these user stories would help address key barriers to adoption or -.. operation. - -.. Some examples of information that might be included here are applicable market -.. segments, workloads, user bases, etc. and any associated data. Please replace -.. "None." with the appropriate data. - -None. - -Requirements Specification --------------------------- - -Use Cases -+++++++++ -.. This section is mandatory. You may submit multiple use cases in a single -.. submission as long as they are inter-related and can be associated with a -.. single epic and/or function. If the use cases are explaining goals that -.. fall under different epics/themes then please complete a separate submission -.. for each group of use cases. Please replace "None." with the appropriate -.. data. - -.. Please provide a unique three character reference and three digit number for -.. each use case - -.. A list of use cases targeted at OpenStack UX Personas, ideally in this -.. or a similar format: - -.. * XXX### As ``_, I want to so that - -This section utilizes the `OpenStack UX Personas`_. - -None. - -.. _OpenStack UX Personas: http://docs.openstack.org/contributor-guide/ux-ui-guidelines/ux-personas.html -.. _: http://docs.openstack.org/contributor-guide/ux-ui-guidelines/ux-personas/ - -Usage Scenario Examples -+++++++++++++++++++++++ -.. This section is mandatory. -.. In order to explain your use cases, if possible, provide an example in the -.. form of a scenario to show how the specified user type might interact with the -.. use case and what they might expect. An example of a usage scenario can be -.. found at http://agilemodeling.com/artifacts/usageScenario.htm of a currently -.. implemented or documented planned solution. Please replace "None." with the -.. appropriate data. - -.. If you have multiple usage scenarios/examples (the more the merrier) you may -.. want to use a numbered list with a title for each one, like the following: - -.. 1. Usage Scenario Title a. 1st Step b. 2nd Step 2. Usage Scenario Title a. 1st -.. Step b. 2nd Step 3. [...] - -None. - -Acceptance Criteria -+++++++++++++++++++ -.. This section is mandatory -.. In order to define completed implementation of a user story, provide -.. detailed definitions of acceptance criteria for these stories. This should -.. include where applicable the specific project set appropriate, the user -.. focused experience and in some cases references to types of specific -.. artifacts. - -.. Please reference the use cases by three character and three number -.. references defined above. - -.. Ex. ABC123 - All Interop Projects obtain tag "FOO" - -None. - -Related User Stories -++++++++++++++++++++ -.. This section is mandatory. -.. If there are related user stories that have some overlap in the problem domain or -.. that you perceive may partially share requirements or a solution, reference them -.. here. - -None. - -*Requirements* -++++++++++++++ -.. This section is optional. It might be useful to specify -.. additional requirements that should be considered but may not be -.. apparent through the use cases and usage examples. This information will help -.. the development be aware of any additional known constraints that need to be met -.. for adoption of the newly implemented features/functionality. Use this section -.. to define the functions that must be available or any specific technical -.. requirements that exist in order to successfully support your use case. If there -.. are requirements that are external to OpenStack, note them as such. Please -.. always add a comprehensible description to ensure that people understand your -.. need. - -.. * 1st Requirement -.. * 2nd Requirement -.. * [...] - -None. - -*External References* -+++++++++++++++++++++ -.. This section is optional. -.. Please use this section to add references for standards or well-defined -.. mechanisms. You can also use this section to reference existing functionality -.. that fits your user story outside of OpenStack. If any of your requirements -.. specifically call for the implementation of a standard or protocol or other -.. well-defined mechanism, use this section to list them. - -None. - -*Rejected User Stories / Usage Scenarios* ------------------------------------------ -.. This is optional -.. Please fill out this section after a User Story has been submitted as a -.. cross project spec to highlight any user stories deemed out of scope of the -.. relevant cross project spec. - -None. - -Glossary --------- -.. This section is optional. -.. It is highly suggested that you define any terms, -.. abbreviations that are not commonly used in order to ensure -.. that your user story is understood properly. - -.. Provide a list of acronyms, their expansions, and what they actually mean in -.. general language here. Define any terms that are specific to your problem -.. domain. If there are devices, appliances, or software stacks that you expect to -.. interact with OpenStack, list them here. - -.. Remember: OpenStack is used for a large number of deployments, and the better -.. you communicate your user story, the more likely it is to be considered by the -.. project teams and the product working group. - -.. Examples: -.. **reST** reStructuredText is a simple markup language -.. **TLA** Three-Letter Abbreviation is an abbreviation consisting of three letters -.. **xyz** Another example abbreviation