Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
On Fri, Nov 28, 2014 at 10:32 PM, Steve Gordon wrote: > - Original Message - > > From: "Deepak Shetty" > > To: "OpenStack Development Mailing List (not for usage questions)" < > openstack-dev@lists.openstack.org> > > > > But isn't *-specs comes very early in the process where you have an > > idea/proposal of a feature, u don't have it yet implemented. Hence specs > > just end up with Para's on how the feature is supposed to work, but > doesn't > > include any real world screen shots as the code is not yet ready at that > > point of time. Along with patch it would make more sense, since the > author > > would have tested it so it isn't a big overhead to catch those cli screen > > shots and put it in a .txt or .md file so that patch reviewers can see > the > > patch in action and hence can review more effectively > > > > thanx, > > deepak > > Sure but in the original email you listed a number of other items, not > just CLI screen shots, including: > > > >> > 1) What changes are needed in manila.conf to make this work > > >> > 2) How to use the cli with this change incorporated > > >> > 3) Some screen shots of actual usage > > >> > 4) Any caution/caveats that one has to keep in mind while using this > > Ideally I see 1, 2, and 4 as things that should be added to the spec > (retrospectively if necessary) to ensure that it maintains an accurate > record of the feature. I can see potential benefits to including listings > of real world usage (3) in the client projects, but I don't think all of > the items listed belong there. > Agree, IMHO (2) and (3) will be possible only when patch is ready, others can be part of spec. thanx, deepak ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
- Original Message - > From: "Deepak Shetty" > To: "OpenStack Development Mailing List (not for usage questions)" > > > But isn't *-specs comes very early in the process where you have an > idea/proposal of a feature, u don't have it yet implemented. Hence specs > just end up with Para's on how the feature is supposed to work, but doesn't > include any real world screen shots as the code is not yet ready at that > point of time. Along with patch it would make more sense, since the author > would have tested it so it isn't a big overhead to catch those cli screen > shots and put it in a .txt or .md file so that patch reviewers can see the > patch in action and hence can review more effectively > > thanx, > deepak Sure but in the original email you listed a number of other items, not just CLI screen shots, including: > >> > 1) What changes are needed in manila.conf to make this work > >> > 2) How to use the cli with this change incorporated > >> > 3) Some screen shots of actual usage > >> > 4) Any caution/caveats that one has to keep in mind while using this Ideally I see 1, 2, and 4 as things that should be added to the spec (retrospectively if necessary) to ensure that it maintains an accurate record of the feature. I can see potential benefits to including listings of real world usage (3) in the client projects, but I don't think all of the items listed belong there. -Steve ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
Current *-specs already include sections like "Data Model Impact/REST Api Impact etc". So what about including a new section like "UseCase examples", which can be updated as a separate patch once the associated CLI changes are merged? Thanks, --Sridhar. On 11/27/2014 10:19 AM, Deepak Shetty wrote: But isn't *-specs comes very early in the process where you have an idea/proposal of a feature, u don't have it yet implemented. Hence specs just end up with Para's on how the feature is supposed to work, but doesn't include any real world screen shots as the code is not yet ready at that point of time. Along with patch it would make more sense, since the author would have tested it so it isn't a big overhead to catch those cli screen shots and put it in a .txt or .md file so that patch reviewers can see the patch in action and hence can review more effectively thanx, deepak On Thu, Nov 27, 2014 at 8:30 AM, Dolph Mathews mailto:dolph.math...@gmail.com>> wrote: On Wed, Nov 26, 2014 at 1:15 PM, Steve Gordon mailto:sgor...@redhat.com>> wrote: - Original Message - > From: "Deepak Shetty" mailto:dpkshe...@gmail.com>> > To: "OpenStack Development Mailing List (not for usage questions)" mailto:openstack-dev@lists.openstack.org>> > > Hi stackers, >I was having this thought which i believe applies to all projects of > openstack (Hence All in the subject tag) > > My proposal is to have examples or usecase folder in each project which has > info on how to use the feature/enhancement (which was submitted as part of > a gerrit patch) > In short, a description with screen shots (cli, not GUI) which should be > submitted (optionally or mandatory) along with patch (liek how testcases > are now enforced) > > I would like to take an example to explain. Take this patch @ > https://review.openstack.org/#/c/127587/ which adds a default volume type > in Manila > > Now it would have been good if we could have a .txt or .md file alogn with > the patch that explains : > > 1) What changes are needed in manila.conf to make this work > > 2) How to use the cli with this change incorporated > > 3) Some screen shots of actual usage (Now the author/submitted would have > tested in devstack before sending patch, so just copying those cli screen > shots wouldn't be too big of a deal) > > 4) Any caution/caveats that one has to keep in mind while using this > > It can be argued that some of the above is satisfied via commit msg and > lookign at test cases. > But i personally feel that those still doesn't give a good visualization of > how a feature patch works in reality > > Adding such a example/usecase file along with patch helps in multiple ways: > > 1) It helps the reviewer get a good picture of how/which clis are affected > and how this patch fits in the flow > > 2) It helps documentor get a good view of how this patch adds value, hence > can document it better > > 3) It may help the author or anyone else write a good detailed blog post > using the examples/usecase as a reference > > 4) Since this becomes part of the patch and hence git log, if the > feature/cli/flow changes in future, we can always refer to how the feature > was designed, worked when it was first posted by looking at the example > usecase > > 5) It helps add a lot of clarity to the patch, since we know how the author > tested it and someone can point missing flows or issues (which otherwise > now has to be visualised) > > 6) I feel this will help attract more reviewers to the patch, since now its > more clear what this patch affects, how it affects and how flows are > changing, even a novice reviewer can feel more comfortable and be confident > to provide comments. > > Thoughts ? I would argue that for the projects that use *-specs repositories this is the type of detail we would like to see in the specifications associated with the feature themselves rather than creating another separate mechanism. For the projects that don't use specs repositories (e.g. Manila) maybe this demand is an indication they should be considering them? +1 this is describing exactly what I expect out of *-specs. -Steve ___ OpenStack-dev mailing lis
Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
On Thu, Nov 27, 2014 at 3:47 PM, Duncan Thomas wrote: > I'm not sure about making it mandatory, but I can certainly see the > benefits of doing this in some cases. Maybe we can start by creating the > area and making the doc optional, and allow reviews to ask for it to be > added where they consider it useful? > +1 - to begin with optional seems good. We can make it mandatory or remove it if we don't see value over time. > > Sometimes (often in cinder), a feature gets written well before the > cinder-cli part gets written, but I guess you can still document via curl > or whatever testing mechanism you used - a separate patch can improve the > doc later once the cli part is written. > My proposal was to send the doc as part of the cli patch, so the doc / screen shots will be latest > My one big worry, as with all documentation, is that we'll end up with a > large amount of stale documentation and nobody motivated to fix it. > If the doc is part of the patch that adds the feature/functionality, there will be less chance of it being stale. Yes if someone changed/modified the way it works, it will be thru some other patch, so the doc accompanying that patch should modify the existing doc and not create a new one. I can see here that we may have issues on how to figure which doc maps to which patch/functionality as the docs added grows over time thanx, deepak ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
I'm not sure about making it mandatory, but I can certainly see the benefits of doing this in some cases. Maybe we can start by creating the area and making the doc optional, and allow reviews to ask for it to be added where they consider it useful? Sometimes (often in cinder), a feature gets written well before the cinder-cli part gets written, but I guess you can still document via curl or whatever testing mechanism you used - a separate patch can improve the doc later once the cli part is written. My one big worry, as with all documentation, is that we'll end up with a large amount of stale documentation and nobody motivated to fix it. On 27 November 2014 at 06:49, Deepak Shetty wrote: > But isn't *-specs comes very early in the process where you have an > idea/proposal of a feature, u don't have it yet implemented. Hence specs > just end up with Para's on how the feature is supposed to work, but doesn't > include any real world screen shots as the code is not yet ready at that > point of time. Along with patch it would make more sense, since the author > would have tested it so it isn't a big overhead to catch those cli screen > shots and put it in a .txt or .md file so that patch reviewers can see the > patch in action and hence can review more effectively > > thanx, > deepak > > > On Thu, Nov 27, 2014 at 8:30 AM, Dolph Mathews > wrote: > >> >> On Wed, Nov 26, 2014 at 1:15 PM, Steve Gordon wrote: >> >>> - Original Message - >>> > From: "Deepak Shetty" >>> > To: "OpenStack Development Mailing List (not for usage questions)" < >>> openstack-dev@lists.openstack.org> >>> > >>> > Hi stackers, >>> >I was having this thought which i believe applies to all projects of >>> > openstack (Hence All in the subject tag) >>> > >>> > My proposal is to have examples or usecase folder in each project >>> which has >>> > info on how to use the feature/enhancement (which was submitted as >>> part of >>> > a gerrit patch) >>> > In short, a description with screen shots (cli, not GUI) which should >>> be >>> > submitted (optionally or mandatory) along with patch (liek how >>> testcases >>> > are now enforced) >>> > >>> > I would like to take an example to explain. Take this patch @ >>> > https://review.openstack.org/#/c/127587/ which adds a default volume >>> type >>> > in Manila >>> > >>> > Now it would have been good if we could have a .txt or .md file alogn >>> with >>> > the patch that explains : >>> > >>> > 1) What changes are needed in manila.conf to make this work >>> > >>> > 2) How to use the cli with this change incorporated >>> > >>> > 3) Some screen shots of actual usage (Now the author/submitted would >>> have >>> > tested in devstack before sending patch, so just copying those cli >>> screen >>> > shots wouldn't be too big of a deal) >>> > >>> > 4) Any caution/caveats that one has to keep in mind while using this >>> > >>> > It can be argued that some of the above is satisfied via commit msg and >>> > lookign at test cases. >>> > But i personally feel that those still doesn't give a good >>> visualization of >>> > how a feature patch works in reality >>> > >>> > Adding such a example/usecase file along with patch helps in multiple >>> ways: >>> > >>> > 1) It helps the reviewer get a good picture of how/which clis are >>> affected >>> > and how this patch fits in the flow >>> > >>> > 2) It helps documentor get a good view of how this patch adds value, >>> hence >>> > can document it better >>> > >>> > 3) It may help the author or anyone else write a good detailed blog >>> post >>> > using the examples/usecase as a reference >>> > >>> > 4) Since this becomes part of the patch and hence git log, if the >>> > feature/cli/flow changes in future, we can always refer to how the >>> feature >>> > was designed, worked when it was first posted by looking at the example >>> > usecase >>> > >>> > 5) It helps add a lot of clarity to the patch, since we know how the >>> author >>> > tested it and someone can point missing flows or issues (which >>> otherwise >>> > now has to be visualised) >>> > >>> > 6) I feel this will help attract more reviewers to the patch, since >>> now its >>> > more clear what this patch affects, how it affects and how flows are >>> > changing, even a novice reviewer can feel more comfortable and be >>> confident >>> > to provide comments. >>> > >>> > Thoughts ? >>> >>> I would argue that for the projects that use *-specs repositories this >>> is the type of detail we would like to see in the specifications associated >>> with the feature themselves rather than creating another separate >>> mechanism. For the projects that don't use specs repositories (e.g. Manila) >>> maybe this demand is an indication they should be considering them? >>> >> >> +1 this is describing exactly what I expect out of *-specs. >> >> >>> >>> -Steve >>> >>> ___ >>> OpenStack-dev mailing list >>> OpenStack-dev@lists.openstack.org >>> http://lists.openstack.org/c
Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
But isn't *-specs comes very early in the process where you have an idea/proposal of a feature, u don't have it yet implemented. Hence specs just end up with Para's on how the feature is supposed to work, but doesn't include any real world screen shots as the code is not yet ready at that point of time. Along with patch it would make more sense, since the author would have tested it so it isn't a big overhead to catch those cli screen shots and put it in a .txt or .md file so that patch reviewers can see the patch in action and hence can review more effectively thanx, deepak On Thu, Nov 27, 2014 at 8:30 AM, Dolph Mathews wrote: > > On Wed, Nov 26, 2014 at 1:15 PM, Steve Gordon wrote: > >> - Original Message - >> > From: "Deepak Shetty" >> > To: "OpenStack Development Mailing List (not for usage questions)" < >> openstack-dev@lists.openstack.org> >> > >> > Hi stackers, >> >I was having this thought which i believe applies to all projects of >> > openstack (Hence All in the subject tag) >> > >> > My proposal is to have examples or usecase folder in each project which >> has >> > info on how to use the feature/enhancement (which was submitted as part >> of >> > a gerrit patch) >> > In short, a description with screen shots (cli, not GUI) which should be >> > submitted (optionally or mandatory) along with patch (liek how testcases >> > are now enforced) >> > >> > I would like to take an example to explain. Take this patch @ >> > https://review.openstack.org/#/c/127587/ which adds a default volume >> type >> > in Manila >> > >> > Now it would have been good if we could have a .txt or .md file alogn >> with >> > the patch that explains : >> > >> > 1) What changes are needed in manila.conf to make this work >> > >> > 2) How to use the cli with this change incorporated >> > >> > 3) Some screen shots of actual usage (Now the author/submitted would >> have >> > tested in devstack before sending patch, so just copying those cli >> screen >> > shots wouldn't be too big of a deal) >> > >> > 4) Any caution/caveats that one has to keep in mind while using this >> > >> > It can be argued that some of the above is satisfied via commit msg and >> > lookign at test cases. >> > But i personally feel that those still doesn't give a good >> visualization of >> > how a feature patch works in reality >> > >> > Adding such a example/usecase file along with patch helps in multiple >> ways: >> > >> > 1) It helps the reviewer get a good picture of how/which clis are >> affected >> > and how this patch fits in the flow >> > >> > 2) It helps documentor get a good view of how this patch adds value, >> hence >> > can document it better >> > >> > 3) It may help the author or anyone else write a good detailed blog post >> > using the examples/usecase as a reference >> > >> > 4) Since this becomes part of the patch and hence git log, if the >> > feature/cli/flow changes in future, we can always refer to how the >> feature >> > was designed, worked when it was first posted by looking at the example >> > usecase >> > >> > 5) It helps add a lot of clarity to the patch, since we know how the >> author >> > tested it and someone can point missing flows or issues (which otherwise >> > now has to be visualised) >> > >> > 6) I feel this will help attract more reviewers to the patch, since now >> its >> > more clear what this patch affects, how it affects and how flows are >> > changing, even a novice reviewer can feel more comfortable and be >> confident >> > to provide comments. >> > >> > Thoughts ? >> >> I would argue that for the projects that use *-specs repositories this is >> the type of detail we would like to see in the specifications associated >> with the feature themselves rather than creating another separate >> mechanism. For the projects that don't use specs repositories (e.g. Manila) >> maybe this demand is an indication they should be considering them? >> > > +1 this is describing exactly what I expect out of *-specs. > > >> >> -Steve >> >> ___ >> OpenStack-dev mailing list >> OpenStack-dev@lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> > > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
On Wed, Nov 26, 2014 at 1:15 PM, Steve Gordon wrote: > - Original Message - > > From: "Deepak Shetty" > > To: "OpenStack Development Mailing List (not for usage questions)" < > openstack-dev@lists.openstack.org> > > > > Hi stackers, > >I was having this thought which i believe applies to all projects of > > openstack (Hence All in the subject tag) > > > > My proposal is to have examples or usecase folder in each project which > has > > info on how to use the feature/enhancement (which was submitted as part > of > > a gerrit patch) > > In short, a description with screen shots (cli, not GUI) which should be > > submitted (optionally or mandatory) along with patch (liek how testcases > > are now enforced) > > > > I would like to take an example to explain. Take this patch @ > > https://review.openstack.org/#/c/127587/ which adds a default volume > type > > in Manila > > > > Now it would have been good if we could have a .txt or .md file alogn > with > > the patch that explains : > > > > 1) What changes are needed in manila.conf to make this work > > > > 2) How to use the cli with this change incorporated > > > > 3) Some screen shots of actual usage (Now the author/submitted would have > > tested in devstack before sending patch, so just copying those cli screen > > shots wouldn't be too big of a deal) > > > > 4) Any caution/caveats that one has to keep in mind while using this > > > > It can be argued that some of the above is satisfied via commit msg and > > lookign at test cases. > > But i personally feel that those still doesn't give a good visualization > of > > how a feature patch works in reality > > > > Adding such a example/usecase file along with patch helps in multiple > ways: > > > > 1) It helps the reviewer get a good picture of how/which clis are > affected > > and how this patch fits in the flow > > > > 2) It helps documentor get a good view of how this patch adds value, > hence > > can document it better > > > > 3) It may help the author or anyone else write a good detailed blog post > > using the examples/usecase as a reference > > > > 4) Since this becomes part of the patch and hence git log, if the > > feature/cli/flow changes in future, we can always refer to how the > feature > > was designed, worked when it was first posted by looking at the example > > usecase > > > > 5) It helps add a lot of clarity to the patch, since we know how the > author > > tested it and someone can point missing flows or issues (which otherwise > > now has to be visualised) > > > > 6) I feel this will help attract more reviewers to the patch, since now > its > > more clear what this patch affects, how it affects and how flows are > > changing, even a novice reviewer can feel more comfortable and be > confident > > to provide comments. > > > > Thoughts ? > > I would argue that for the projects that use *-specs repositories this is > the type of detail we would like to see in the specifications associated > with the feature themselves rather than creating another separate > mechanism. For the projects that don't use specs repositories (e.g. Manila) > maybe this demand is an indication they should be considering them? > +1 this is describing exactly what I expect out of *-specs. > > -Steve > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
- Original Message - > From: "Deepak Shetty" > To: "OpenStack Development Mailing List (not for usage questions)" > > > Hi stackers, >I was having this thought which i believe applies to all projects of > openstack (Hence All in the subject tag) > > My proposal is to have examples or usecase folder in each project which has > info on how to use the feature/enhancement (which was submitted as part of > a gerrit patch) > In short, a description with screen shots (cli, not GUI) which should be > submitted (optionally or mandatory) along with patch (liek how testcases > are now enforced) > > I would like to take an example to explain. Take this patch @ > https://review.openstack.org/#/c/127587/ which adds a default volume type > in Manila > > Now it would have been good if we could have a .txt or .md file alogn with > the patch that explains : > > 1) What changes are needed in manila.conf to make this work > > 2) How to use the cli with this change incorporated > > 3) Some screen shots of actual usage (Now the author/submitted would have > tested in devstack before sending patch, so just copying those cli screen > shots wouldn't be too big of a deal) > > 4) Any caution/caveats that one has to keep in mind while using this > > It can be argued that some of the above is satisfied via commit msg and > lookign at test cases. > But i personally feel that those still doesn't give a good visualization of > how a feature patch works in reality > > Adding such a example/usecase file along with patch helps in multiple ways: > > 1) It helps the reviewer get a good picture of how/which clis are affected > and how this patch fits in the flow > > 2) It helps documentor get a good view of how this patch adds value, hence > can document it better > > 3) It may help the author or anyone else write a good detailed blog post > using the examples/usecase as a reference > > 4) Since this becomes part of the patch and hence git log, if the > feature/cli/flow changes in future, we can always refer to how the feature > was designed, worked when it was first posted by looking at the example > usecase > > 5) It helps add a lot of clarity to the patch, since we know how the author > tested it and someone can point missing flows or issues (which otherwise > now has to be visualised) > > 6) I feel this will help attract more reviewers to the patch, since now its > more clear what this patch affects, how it affects and how flows are > changing, even a novice reviewer can feel more comfortable and be confident > to provide comments. > > Thoughts ? I would argue that for the projects that use *-specs repositories this is the type of detail we would like to see in the specifications associated with the feature themselves rather than creating another separate mechanism. For the projects that don't use specs repositories (e.g. Manila) maybe this demand is an indication they should be considering them? -Steve ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
Hi Valeriy, I know about docs, but this was a proposal to provide small doc which are patch specific as that helps reviewers and other doc writers I have many a times seen people asking on IRC or list on how to test this patch, or i did this with your patch but didn't work , such iterations can be reduced if we can have small docs (in free flowing text to begin with) associated with each patch than can help people other than author to understand what/how the patch adds functionality, which will improve the overall review quality and reviewers in general thanx, deepak P.S. I took the Manila patch just as an example , nothing specific about it :) On Wed, Nov 26, 2014 at 3:40 PM, Valeriy Ponomaryov < vponomar...@mirantis.com> wrote: > Hi Deepak, > > Docs are present in any project already, according to example with manila > - https://github.com/openstack/manila/tree/master/doc/source > > It is used for docs on http://docs.openstack.org/ , also everyone if able > to contribute to it. > > See docs built on basis of files from manila repo: > http://docs.openstack.org/developer/manila/ > > For most of projects we have already useful resource: > http://docs.openstack.org/cli-reference/content/ > > In conclusion I can say that it is question more to the organization of > creation such docs than possibility to create it in general. > > Regards, > Valeriy Ponomaryov > > On Wed, Nov 26, 2014 at 8:01 AM, Deepak Shetty > wrote: > >> Hi stackers, >>I was having this thought which i believe applies to all projects of >> openstack (Hence All in the subject tag) >> >> My proposal is to have examples or usecase folder in each project which >> has info on how to use the feature/enhancement (which was submitted as part >> of a gerrit patch) >> In short, a description with screen shots (cli, not GUI) which should be >> submitted (optionally or mandatory) along with patch (liek how testcases >> are now enforced) >> >> I would like to take an example to explain. Take this patch @ >> https://review.openstack.org/#/c/127587/ which adds a default volume >> type in Manila >> >> Now it would have been good if we could have a .txt or .md file alogn >> with the patch that explains : >> >> 1) What changes are needed in manila.conf to make this work >> >> 2) How to use the cli with this change incorporated >> >> 3) Some screen shots of actual usage (Now the author/submitted would have >> tested in devstack before sending patch, so just copying those cli screen >> shots wouldn't be too big of a deal) >> >> 4) Any caution/caveats that one has to keep in mind while using this >> >> It can be argued that some of the above is satisfied via commit msg and >> lookign at test cases. >> But i personally feel that those still doesn't give a good visualization >> of how a feature patch works in reality >> >> Adding such a example/usecase file along with patch helps in multiple >> ways: >> >> 1) It helps the reviewer get a good picture of how/which clis are >> affected and how this patch fits in the flow >> >> 2) It helps documentor get a good view of how this patch adds value, >> hence can document it better >> >> 3) It may help the author or anyone else write a good detailed blog post >> using the examples/usecase as a reference >> >> 4) Since this becomes part of the patch and hence git log, if the >> feature/cli/flow changes in future, we can always refer to how the feature >> was designed, worked when it was first posted by looking at the example >> usecase >> >> 5) It helps add a lot of clarity to the patch, since we know how the >> author tested it and someone can point missing flows or issues (which >> otherwise now has to be visualised) >> >> 6) I feel this will help attract more reviewers to the patch, since now >> its more clear what this patch affects, how it affects and how flows are >> changing, even a novice reviewer can feel more comfortable and be confident >> to provide comments. >> >> Thoughts ? >> >> thanx, >> deepak >> >> >> ___ >> OpenStack-dev mailing list >> OpenStack-dev@lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> >> > > > -- > Kind Regards > Valeriy Ponomaryov > www.mirantis.com > vponomar...@mirantis.com > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
Hi Deepak, Docs are present in any project already, according to example with manila - https://github.com/openstack/manila/tree/master/doc/source It is used for docs on http://docs.openstack.org/ , also everyone if able to contribute to it. See docs built on basis of files from manila repo: http://docs.openstack.org/developer/manila/ For most of projects we have already useful resource: http://docs.openstack.org/cli-reference/content/ In conclusion I can say that it is question more to the organization of creation such docs than possibility to create it in general. Regards, Valeriy Ponomaryov On Wed, Nov 26, 2014 at 8:01 AM, Deepak Shetty wrote: > Hi stackers, >I was having this thought which i believe applies to all projects of > openstack (Hence All in the subject tag) > > My proposal is to have examples or usecase folder in each project which > has info on how to use the feature/enhancement (which was submitted as part > of a gerrit patch) > In short, a description with screen shots (cli, not GUI) which should be > submitted (optionally or mandatory) along with patch (liek how testcases > are now enforced) > > I would like to take an example to explain. Take this patch @ > https://review.openstack.org/#/c/127587/ which adds a default volume type > in Manila > > Now it would have been good if we could have a .txt or .md file alogn with > the patch that explains : > > 1) What changes are needed in manila.conf to make this work > > 2) How to use the cli with this change incorporated > > 3) Some screen shots of actual usage (Now the author/submitted would have > tested in devstack before sending patch, so just copying those cli screen > shots wouldn't be too big of a deal) > > 4) Any caution/caveats that one has to keep in mind while using this > > It can be argued that some of the above is satisfied via commit msg and > lookign at test cases. > But i personally feel that those still doesn't give a good visualization > of how a feature patch works in reality > > Adding such a example/usecase file along with patch helps in multiple ways: > > 1) It helps the reviewer get a good picture of how/which clis are affected > and how this patch fits in the flow > > 2) It helps documentor get a good view of how this patch adds value, hence > can document it better > > 3) It may help the author or anyone else write a good detailed blog post > using the examples/usecase as a reference > > 4) Since this becomes part of the patch and hence git log, if the > feature/cli/flow changes in future, we can always refer to how the feature > was designed, worked when it was first posted by looking at the example > usecase > > 5) It helps add a lot of clarity to the patch, since we know how the > author tested it and someone can point missing flows or issues (which > otherwise now has to be visualised) > > 6) I feel this will help attract more reviewers to the patch, since now > its more clear what this patch affects, how it affects and how flows are > changing, even a novice reviewer can feel more comfortable and be confident > to provide comments. > > Thoughts ? > > thanx, > deepak > > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > -- Kind Regards Valeriy Ponomaryov www.mirantis.com vponomar...@mirantis.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
Hi stackers, I was having this thought which i believe applies to all projects of openstack (Hence All in the subject tag) My proposal is to have examples or usecase folder in each project which has info on how to use the feature/enhancement (which was submitted as part of a gerrit patch) In short, a description with screen shots (cli, not GUI) which should be submitted (optionally or mandatory) along with patch (liek how testcases are now enforced) I would like to take an example to explain. Take this patch @ https://review.openstack.org/#/c/127587/ which adds a default volume type in Manila Now it would have been good if we could have a .txt or .md file alogn with the patch that explains : 1) What changes are needed in manila.conf to make this work 2) How to use the cli with this change incorporated 3) Some screen shots of actual usage (Now the author/submitted would have tested in devstack before sending patch, so just copying those cli screen shots wouldn't be too big of a deal) 4) Any caution/caveats that one has to keep in mind while using this It can be argued that some of the above is satisfied via commit msg and lookign at test cases. But i personally feel that those still doesn't give a good visualization of how a feature patch works in reality Adding such a example/usecase file along with patch helps in multiple ways: 1) It helps the reviewer get a good picture of how/which clis are affected and how this patch fits in the flow 2) It helps documentor get a good view of how this patch adds value, hence can document it better 3) It may help the author or anyone else write a good detailed blog post using the examples/usecase as a reference 4) Since this becomes part of the patch and hence git log, if the feature/cli/flow changes in future, we can always refer to how the feature was designed, worked when it was first posted by looking at the example usecase 5) It helps add a lot of clarity to the patch, since we know how the author tested it and someone can point missing flows or issues (which otherwise now has to be visualised) 6) I feel this will help attract more reviewers to the patch, since now its more clear what this patch affects, how it affects and how flows are changing, even a novice reviewer can feel more comfortable and be confident to provide comments. Thoughts ? thanx, deepak ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
