Re: [openstack-dev] [Fuel] Documentation Process changed
We definitely need to assign these bugs to the fuel-docs team. And there is a good point from Alexandra Fedorova that commit message needs to have enough information for tech writer. And reviewers should not merge fixes that do not apply this rule. Otherwise we will end up with new bottlenecks. One bottleneck is bug triage with bunch of badly formatted bug reports every day. And another bottleneck is bugs on fuel-docs team. They will have to drive each bug, find a developer, get the information, find a place for it and so on. Let's try to make their life easier. And another point. I don't like bug tags. You can not see them from the milestone page. You can not filter out documentation bugs even from advanced search page. We could try to add [doc] prefix for bug subjects automatically. It will help a little bit. On Thu, Oct 9, 2014 at 12:27 AM, Sergii Golovatiuk sgolovat...@mirantis.com wrote: Hi, Dima, that's really good approach. Mike, technical writer may ask developer and assign bug to him/her if bug impacts developer documentation only. Best Regards, Sergii Golovatiuk On 08 Oct 2014, at 21:08, Mike Scherbakov mscherba...@mirantis.com wrote: Thanks Dmitry, let's try to go this way and correct process if needed when we get first results. Where is your 80% dev vs user docs figure coming from? it's no more than my guess. We will see real number over time. On Wed, Oct 8, 2014 at 10:31 PM, Dmitry Borodaenko dborodae...@mirantis.com wrote: At the moment OpenStack infrastructure doesn't allow to customize the bugs it creates, we should propose a patch at some point to implement that. When we do, I think we should assign such bugs automatically to fuel-docs team. I don't think we should separate user and dev docs bugs, we're working in the opposite direction towards merging dev docs into fuel-docs: https://review.openstack.org/124551 Where is your 80% dev vs user docs figure coming from? I think that whether it's dev or user documentation, a technical writer should drive the process, collect information from the commit author, and add it to the right documentation areas. It's commit author's responsibility to provide an informative commit message in the first place, to answer technical writer's questions, and to review docs commits that address the DocImpact bug. On Oct 8, 2014 10:59 AM, Mike Scherbakov mscherba...@mirantis.com wrote: Very good improvement in our documentation process. Is there a way to configure it, so bugs would be created with tag docs automatically? It would simplify triaging process I believe. From the other hand, as far as I understand, up to 80% of commits with DocImpact will impact development documentation (or it's intended to be affecting only user documentation?). It would be hard for tech writers, who are mostly specialized in Fuel user docs, to work on low-level details of how, let's say, l23network [1] works. Do we want to separate docs bugs somehow, user/dev? In other words, what would be the flow, who becomes responsible for fixing bugs created automatically by Infra? [1] https://github.com/stackforge/fuel-library/tree/master/deployment/puppet/l23network On Wed, Oct 8, 2014 at 5:34 PM, Sergii Golovatiuk sgolovat...@mirantis.com wrote: Hi, On Fuel Summit '2014 we discussed our Documentation process. According to follow up we aligned it to OpenStack 'DocImpact' process. The new process has been tested on background by me and Bogdan Dobrelya. Today, I have updated Fuel Documentation Process so we are making it official. Why? Developer perspective: It gives more flexibility for the developers to participate in Documentation Process. Every time when the Reviewer sees that patch requires Documentation update, it may ask the Commiter to update 'Commit Message' with DocImpact message. Once patch passes the review Openstack Infra will trigger a new bug in Launchpad that should be assigned to Fuel Documentation team. From Fuel Documentation Team perspective: When Fuel Documentation Team sees this bug they know who was the commiter and reviewers and whom they should add for documentation review. Community: Community member may ask the developer to put 'DocImpact' message when it's required. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Mike Scherbakov #mihgen ___ 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
Re: [openstack-dev] [Fuel] Documentation Process changed
Filtering bugs by tags works fine in advanced search, the only problem is that you can't combine it with filtering by releases (since that's broken in advanced search and you have to use milestone page for that). On Thu, Oct 9, 2014 at 12:18 PM, Dmitry Pyzhov dpyz...@mirantis.com wrote: We definitely need to assign these bugs to the fuel-docs team. And there is a good point from Alexandra Fedorova that commit message needs to have enough information for tech writer. And reviewers should not merge fixes that do not apply this rule. Otherwise we will end up with new bottlenecks. One bottleneck is bug triage with bunch of badly formatted bug reports every day. And another bottleneck is bugs on fuel-docs team. They will have to drive each bug, find a developer, get the information, find a place for it and so on. Let's try to make their life easier. And another point. I don't like bug tags. You can not see them from the milestone page. You can not filter out documentation bugs even from advanced search page. We could try to add [doc] prefix for bug subjects automatically. It will help a little bit. On Thu, Oct 9, 2014 at 12:27 AM, Sergii Golovatiuk sgolovat...@mirantis.com wrote: Hi, Dima, that's really good approach. Mike, technical writer may ask developer and assign bug to him/her if bug impacts developer documentation only. Best Regards, Sergii Golovatiuk On 08 Oct 2014, at 21:08, Mike Scherbakov mscherba...@mirantis.com wrote: Thanks Dmitry, let's try to go this way and correct process if needed when we get first results. Where is your 80% dev vs user docs figure coming from? it's no more than my guess. We will see real number over time. On Wed, Oct 8, 2014 at 10:31 PM, Dmitry Borodaenko dborodae...@mirantis.com wrote: At the moment OpenStack infrastructure doesn't allow to customize the bugs it creates, we should propose a patch at some point to implement that. When we do, I think we should assign such bugs automatically to fuel-docs team. I don't think we should separate user and dev docs bugs, we're working in the opposite direction towards merging dev docs into fuel-docs: https://review.openstack.org/124551 Where is your 80% dev vs user docs figure coming from? I think that whether it's dev or user documentation, a technical writer should drive the process, collect information from the commit author, and add it to the right documentation areas. It's commit author's responsibility to provide an informative commit message in the first place, to answer technical writer's questions, and to review docs commits that address the DocImpact bug. On Oct 8, 2014 10:59 AM, Mike Scherbakov mscherba...@mirantis.com wrote: Very good improvement in our documentation process. Is there a way to configure it, so bugs would be created with tag docs automatically? It would simplify triaging process I believe. From the other hand, as far as I understand, up to 80% of commits with DocImpact will impact development documentation (or it's intended to be affecting only user documentation?). It would be hard for tech writers, who are mostly specialized in Fuel user docs, to work on low-level details of how, let's say, l23network [1] works. Do we want to separate docs bugs somehow, user/dev? In other words, what would be the flow, who becomes responsible for fixing bugs created automatically by Infra? [1] https://github.com/stackforge/fuel-library/tree/master/deployment/puppet/l23network On Wed, Oct 8, 2014 at 5:34 PM, Sergii Golovatiuk sgolovat...@mirantis.com wrote: Hi, On Fuel Summit '2014 we discussed our Documentation process. According to follow up we aligned it to OpenStack 'DocImpact' process. The new process has been tested on background by me and Bogdan Dobrelya. Today, I have updated Fuel Documentation Process so we are making it official. Why? Developer perspective: It gives more flexibility for the developers to participate in Documentation Process. Every time when the Reviewer sees that patch requires Documentation update, it may ask the Commiter to update 'Commit Message' with DocImpact message. Once patch passes the review Openstack Infra will trigger a new bug in Launchpad that should be assigned to Fuel Documentation team. From Fuel Documentation Team perspective: When Fuel Documentation Team sees this bug they know who was the commiter and reviewers and whom they should add for documentation review. Community: Community member may ask the developer to put 'DocImpact' message when it's required. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Mike Scherbakov #mihgen ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org
[openstack-dev] [Fuel] Documentation Process changed
Hi, On Fuel Summit '2014 we discussed our Documentation process. According to follow up we aligned it to OpenStack 'DocImpact' process. The new process has been tested on background by me and Bogdan Dobrelya. Today, I have updated Fuel Documentation Process https://wiki.openstack.org/wiki/Fuel/How_to_contribute#Documentation so we are making it official. Why? Developer perspective: It gives more flexibility for the developers to participate in Documentation Process. Every time when the Reviewer sees that patch requires Documentation update, it may ask the Commiter to update 'Commit Message' with DocImpact message. Once patch passes the review Openstack Infra will trigger a new bug in Launchpad that should be assigned to Fuel Documentation team. From Fuel Documentation Team perspective: When Fuel Documentation Team sees this bug they know who was the commiter and reviewers and whom they should add for documentation review. Community: Community member may ask the developer to put 'DocImpact' message when it's required. -- Best regards, Sergii Golovatiuk, Skype #golserge IRC #holser ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Fuel] Documentation Process changed
At the moment OpenStack infrastructure doesn't allow to customize the bugs it creates, we should propose a patch at some point to implement that. When we do, I think we should assign such bugs automatically to fuel-docs team. I don't think we should separate user and dev docs bugs, we're working in the opposite direction towards merging dev docs into fuel-docs: https://review.openstack.org/124551 Where is your 80% dev vs user docs figure coming from? I think that whether it's dev or user documentation, a technical writer should drive the process, collect information from the commit author, and add it to the right documentation areas. It's commit author's responsibility to provide an informative commit message in the first place, to answer technical writer's questions, and to review docs commits that address the DocImpact bug. On Oct 8, 2014 10:59 AM, Mike Scherbakov mscherba...@mirantis.com wrote: Very good improvement in our documentation process. Is there a way to configure it, so bugs would be created with tag docs automatically? It would simplify triaging process I believe. From the other hand, as far as I understand, up to 80% of commits with DocImpact will impact development documentation (or it's intended to be affecting only user documentation?). It would be hard for tech writers, who are mostly specialized in Fuel user docs, to work on low-level details of how, let's say, l23network [1] works. Do we want to separate docs bugs somehow, user/dev? In other words, what would be the flow, who becomes responsible for fixing bugs created automatically by Infra? [1] https://github.com/stackforge/fuel-library/tree/master/deployment/puppet/l23network On Wed, Oct 8, 2014 at 5:34 PM, Sergii Golovatiuk sgolovat...@mirantis.com wrote: Hi, On Fuel Summit '2014 we discussed our Documentation process. According to follow up we aligned it to OpenStack 'DocImpact' process. The new process has been tested on background by me and Bogdan Dobrelya. Today, I have updated Fuel Documentation Process so we are making it official. Why? Developer perspective: It gives more flexibility for the developers to participate in Documentation Process. Every time when the Reviewer sees that patch requires Documentation update, it may ask the Commiter to update 'Commit Message' with DocImpact message. Once patch passes the review Openstack Infra will trigger a new bug in Launchpad that should be assigned to Fuel Documentation team. From Fuel Documentation Team perspective: When Fuel Documentation Team sees this bug they know who was the commiter and reviewers and whom they should add for documentation review. Community: Community member may ask the developer to put 'DocImpact' message when it's required. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Fuel] Documentation Process changed
Thanks Dmitry, let's try to go this way and correct process if needed when we get first results. Where is your 80% dev vs user docs figure coming from? it's no more than my guess. We will see real number over time. On Wed, Oct 8, 2014 at 10:31 PM, Dmitry Borodaenko dborodae...@mirantis.com wrote: At the moment OpenStack infrastructure doesn't allow to customize the bugs it creates, we should propose a patch at some point to implement that. When we do, I think we should assign such bugs automatically to fuel-docs team. I don't think we should separate user and dev docs bugs, we're working in the opposite direction towards merging dev docs into fuel-docs: https://review.openstack.org/124551 Where is your 80% dev vs user docs figure coming from? I think that whether it's dev or user documentation, a technical writer should drive the process, collect information from the commit author, and add it to the right documentation areas. It's commit author's responsibility to provide an informative commit message in the first place, to answer technical writer's questions, and to review docs commits that address the DocImpact bug. On Oct 8, 2014 10:59 AM, Mike Scherbakov mscherba...@mirantis.com wrote: Very good improvement in our documentation process. Is there a way to configure it, so bugs would be created with tag docs automatically? It would simplify triaging process I believe. From the other hand, as far as I understand, up to 80% of commits with DocImpact will impact development documentation (or it's intended to be affecting only user documentation?). It would be hard for tech writers, who are mostly specialized in Fuel user docs, to work on low-level details of how, let's say, l23network [1] works. Do we want to separate docs bugs somehow, user/dev? In other words, what would be the flow, who becomes responsible for fixing bugs created automatically by Infra? [1] https://github.com/stackforge/fuel-library/tree/master/deployment/puppet/l23network On Wed, Oct 8, 2014 at 5:34 PM, Sergii Golovatiuk sgolovat...@mirantis.com wrote: Hi, On Fuel Summit '2014 we discussed our Documentation process. According to follow up we aligned it to OpenStack 'DocImpact' process. The new process has been tested on background by me and Bogdan Dobrelya. Today, I have updated Fuel Documentation Process so we are making it official. Why? Developer perspective: It gives more flexibility for the developers to participate in Documentation Process. Every time when the Reviewer sees that patch requires Documentation update, it may ask the Commiter to update 'Commit Message' with DocImpact message. Once patch passes the review Openstack Infra will trigger a new bug in Launchpad that should be assigned to Fuel Documentation team. From Fuel Documentation Team perspective: When Fuel Documentation Team sees this bug they know who was the commiter and reviewers and whom they should add for documentation review. Community: Community member may ask the developer to put 'DocImpact' message when it's required. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Mike Scherbakov #mihgen ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Fuel] Documentation Process changed
Hi, Dima, that's really good approach. Mike, technical writer may ask developer and assign bug to him/her if bug impacts developer documentation only. Best Regards, Sergii Golovatiuk On 08 Oct 2014, at 21:08, Mike Scherbakov mscherba...@mirantis.com wrote: Thanks Dmitry, let's try to go this way and correct process if needed when we get first results. Where is your 80% dev vs user docs figure coming from? it's no more than my guess. We will see real number over time. On Wed, Oct 8, 2014 at 10:31 PM, Dmitry Borodaenko dborodae...@mirantis.com wrote: At the moment OpenStack infrastructure doesn't allow to customize the bugs it creates, we should propose a patch at some point to implement that. When we do, I think we should assign such bugs automatically to fuel-docs team. I don't think we should separate user and dev docs bugs, we're working in the opposite direction towards merging dev docs into fuel-docs: https://review.openstack.org/124551 Where is your 80% dev vs user docs figure coming from? I think that whether it's dev or user documentation, a technical writer should drive the process, collect information from the commit author, and add it to the right documentation areas. It's commit author's responsibility to provide an informative commit message in the first place, to answer technical writer's questions, and to review docs commits that address the DocImpact bug. On Oct 8, 2014 10:59 AM, Mike Scherbakov mscherba...@mirantis.com wrote: Very good improvement in our documentation process. Is there a way to configure it, so bugs would be created with tag docs automatically? It would simplify triaging process I believe. From the other hand, as far as I understand, up to 80% of commits with DocImpact will impact development documentation (or it's intended to be affecting only user documentation?). It would be hard for tech writers, who are mostly specialized in Fuel user docs, to work on low-level details of how, let's say, l23network [1] works. Do we want to separate docs bugs somehow, user/dev? In other words, what would be the flow, who becomes responsible for fixing bugs created automatically by Infra? [1] https://github.com/stackforge/fuel-library/tree/master/deployment/puppet/l23network On Wed, Oct 8, 2014 at 5:34 PM, Sergii Golovatiuk sgolovat...@mirantis.com wrote: Hi, On Fuel Summit '2014 we discussed our Documentation process. According to follow up we aligned it to OpenStack 'DocImpact' process. The new process has been tested on background by me and Bogdan Dobrelya. Today, I have updated Fuel Documentation Process so we are making it official. Why? Developer perspective: It gives more flexibility for the developers to participate in Documentation Process. Every time when the Reviewer sees that patch requires Documentation update, it may ask the Commiter to update 'Commit Message' with DocImpact message. Once patch passes the review Openstack Infra will trigger a new bug in Launchpad that should be assigned to Fuel Documentation team. From Fuel Documentation Team perspective: When Fuel Documentation Team sees this bug they know who was the commiter and reviewers and whom they should add for documentation review. Community: Community member may ask the developer to put 'DocImpact' message when it's required. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Mike Scherbakov #mihgen ___ 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] [Fuel] Documentation process
Sorry I'm so late to the party. Yes, Andreas is right, we simply cannot take on any more DocImpact in openstack-manuals, but it would be great to change the infrastructure to log against a more exact match for the bug tracker for the project with the impacted docs. Looks like you're doing so with https://review.openstack.org/125434 so I'm reviewing there. Some additional protips for devs: There's an indicator called docimpact-group: for each project. In that setting, enter the Launchpad bug project you want bugs automatically logged into. (wow that's strange grammar). Don't use docimpact-group: openstack-manuals unless your project is integrated. We can't blow out our doc bug numbers artificially. Don't use docimpact-group: openstack-manuals for common projects like Oslo, QA, or Infra repos. I'm working on a cleanup patch. No need to use docimpact-group for specs repos or docs repos. We'll cover all this and more at a docs bootstrapping session coming soon! Thanks, Anne On Thu, Sep 25, 2014 at 1:39 AM, Andreas Jaeger a...@suse.com wrote: On 09/24/2014 09:55 PM, Sergii Golovatiuk wrote: Hi, I would like to discuss the documentation process and align it to OpenStack flow. At the moment we add special tags to bugs in Launchpad which is not optimal as everyone can add/remove tags cannot participate in documentation process or enforce documentation process. I suggest to switch to standard workflow that is used by OpenStack community All we need is to move the process of tracking documentation from launchpad to gerrit This process gives more control to individual developers or community for tracking the changes and reflect them in documentation. Every reviewer checks the commit. If he thinks that this commit requires documentation update, he will set -1 with comment message Docs impact required This will force the author of patchset to update commit with DocImpact commit message Our documentation team will get all messages with DocImpact from 'git log'. The documentation team will make a documentation where the author of patch will play a key role. All other reviewers from original patch must give own +1 for documentation update. Patches in fuel-docs may have the same Change-ID as original patch. It will allow us to match documentation and patches in Gerrit. More details about DocImpact flow ban be obtained at https://wiki.openstack.org/wiki/Documentation/DocImpact Currently all bugs filed due to DocImpact land in the openstack-manuals launchpad bug area unless the repository is setup in the infrastructure to push them elsewhere. If you want to move forward with this, please setup first the infrastructure to properly file the bugs, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 ___ 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] [Fuel] Documentation process
On 09/24/2014 09:55 PM, Sergii Golovatiuk wrote: Hi, I would like to discuss the documentation process and align it to OpenStack flow. At the moment we add special tags to bugs in Launchpad which is not optimal as everyone can add/remove tags cannot participate in documentation process or enforce documentation process. I suggest to switch to standard workflow that is used by OpenStack community All we need is to move the process of tracking documentation from launchpad to gerrit This process gives more control to individual developers or community for tracking the changes and reflect them in documentation. Every reviewer checks the commit. If he thinks that this commit requires documentation update, he will set -1 with comment message Docs impact required This will force the author of patchset to update commit with DocImpact commit message Our documentation team will get all messages with DocImpact from 'git log'. The documentation team will make a documentation where the author of patch will play a key role. All other reviewers from original patch must give own +1 for documentation update. Patches in fuel-docs may have the same Change-ID as original patch. It will allow us to match documentation and patches in Gerrit. More details about DocImpact flow ban be obtained at https://wiki.openstack.org/wiki/Documentation/DocImpact Currently all bugs filed due to DocImpact land in the openstack-manuals launchpad bug area unless the repository is setup in the infrastructure to push them elsewhere. If you want to move forward with this, please setup first the infrastructure to properly file the bugs, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [Fuel] Documentation process
Hi, I would like to discuss the documentation process and align it to OpenStack flow. At the moment we add special tags to bugs in Launchpad which is not optimal as everyone can add/remove tags cannot participate in documentation process or enforce documentation process. I suggest to switch to standard workflow that is used by OpenStack community All we need is to move the process of tracking documentation from launchpad to gerrit This process gives more control to individual developers or community for tracking the changes and reflect them in documentation. Every reviewer checks the commit. If he thinks that this commit requires documentation update, he will set -1 with comment message Docs impact required This will force the author of patchset to update commit with DocImpact commit message Our documentation team will get all messages with DocImpact from 'git log'. The documentation team will make a documentation where the author of patch will play a key role. All other reviewers from original patch must give own +1 for documentation update. Patches in fuel-docs may have the same Change-ID as original patch. It will allow us to match documentation and patches in Gerrit. More details about DocImpact flow ban be obtained at https://wiki.openstack.org/wiki/Documentation/DocImpact -- Best regards, Sergii Golovatiuk, Skype #golserge IRC #holser ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev