Re: RE: Issue Management in Apache Projects
Some update from the most recent attempt of Apache Airflow to improve our issue handling using some "new-ish" features available in GitHub: Issue Forms and GitHub Discussions. TL;DR; We don not have yet results but we think in Airflow making the full use of GitHub Form Templates and endorsing the use of GitHub Discussions where appropriate (and at the issue entry time), should help us a lot by "gating" issues better, improving their quality and getting our users into "pre-clasifying" the issues (or indeed using Discussions where it is a better choice). *Problems we observed:* * with the standard MARKDOWN templates we have many issues where people did not provide useful information (version of airflow, operating system etc.) * we had a number of issues where users would simply delete the markdown template content straight away and replaced with their own issue description - without "reproducible steps", or really to ask a question about their deployment problems without even trying to attempt to investigate it. We've ended up with many "discussion" kind of question posted as issues. Then we would "convert" such issues into discussion but it required maintainers comment and explanation. Mostly it was because the users did not even know they can (and should) open a discussion instead. * the markdown templates were difficult to read/fill in - it was not clear what you should do with the parts which were relevant - we left instructions in the comments, which were sometimes left/sometimes deleted, generally the issues were "structur-ish" rather than "structured". * often people opened Airflow 1.10 issues even if it reached End-Of-Life in June (they should open discussions instead - which is still great because even if there are no way we will handle the issues but either us or other users can help them still for workaround or even directing t) *Discovery* Then we discovered that we already can use "Forms for GitHub Issues" (beta feature but it is available for everyone now - https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms). This looked like not only a great way to structure and pre-classify the issues (by the users) but also seems to be a great communication tool with the users. We believe it will allow us to address most of the issues above. Basically instead of committers having to explain the rules over and over and instruct the users how they should report the issues - it's all there explained really clearly and nicely while the user enters the issue. *Solution* We defined forms with required fields that cannot be "skipped". also when you do not fill a "textarea" entry it is marked as "Not Provided" rather than deleted. We added helpful comments and hints as well as explanation in which cases you should use GitHub Discussions (including lack of ability to select 1.10 version and link to open GitHub Discussions) instead of issues (with direct link). We've added logo and welcoming message to "soften" the "more formalized form entry need. We made it clear that if there is no reproduction steps, the users should open GitHub Discussion instead. We've added more issue types - we've separated "Airflow Core", "Airflow Providers" (we have more than 70 providers that extend Airflow's capabilities) and "Airflow Docs" issues - automatically applying correct labels, so we do not have to do triage ourselves. We also created a "maintainer only" issue type with allows to enter pretty much free-form information (for tasks/todos etc.) and we've added a required "checkbox" to confirm you are maintainer, to discourage people from using it to raise their "free form" questions there. We wanted it to be "easy" for committers to enter such "free form" issue but "not easy" to skip structured information by the users - at the same time guiding them to use "Discussions" which are much "easier" to enter any content and ask questions. What is even more - this structured form will allow us to automate some stuff if we find it is needed. For example if someone submits an entry without providing "reproduction steps" we can write a bot to automatically convert such issue into discussion. Or automatically close an issue if someone opens a "free-form" one while not being maintainer. *Demo/Take a look yourselves* You can try it yourself here: https://github.com/apache/airflow/issues/new/choose And see some screenshots how our issue form entries looks like: - https://ibb.co/Lxgx7xn - https://ibb.co/0rYqm1Q - https://ibb.co/fX45nBB - https://ibb.co/dbTR9GV PR introducing it is here: https://github.com/apache/airflow/pull/17855 We really hope it will drive the issue quality up and issue number down eventually. J. On Thu, Jul 15, 2021 at 5:17 PM Jarek Potiuk wrote: > Good luck :). > > On Thu, Jul 15, 2021 at 3:53 PM Erik Ritter wrote: > >> Thank you all for the great advice and thoughts! I see a lot of alignment >> between items suggested
Re: RE: Issue Management in Apache Projects
Jarek Nice summary. I can learn many from it. And setting up a robot to resolve this kind of problems seems a very productive way. Look forward to it. SkyWalking community faces very similar scenarios as Airflow. GitHub discussion does help. Jarek Potiuk 于2021年8月29日 周日上午12:47写道： > Some update from the most recent attempt of Apache Airflow to improve our > issue handling using some "new-ish" features available in GitHub: Issue > Forms and GitHub Discussions. > > TL;DR; We don not have yet results but we think in Airflow making the full > use of GitHub Form Templates and endorsing the use of GitHub Discussions > where appropriate (and at the issue entry time), should help us a lot by > "gating" issues better, improving their quality and getting our users into > "pre-clasifying" the issues (or indeed using Discussions where it is a > better choice). > > *Problems we observed:* > > * with the standard MARKDOWN templates we have many issues where people did > not provide useful information (version of airflow, operating system etc.) > * we had a number of issues where users would simply delete the markdown > template content straight away and replaced with their own issue > description - without "reproducible steps", or really to ask a question > about their deployment problems without even trying to attempt to > investigate it. >We've ended up with many "discussion" kind of question posted as issues. > Then we would "convert" such issues into discussion but it required > maintainers comment and explanation. Mostly it was because the users did > not even know they can (and should) open a discussion instead. > * the markdown templates were difficult to read/fill in - it was not clear > what you should do with the parts which were relevant - we left > instructions in the comments, which were sometimes left/sometimes deleted, > generally the issues were "structur-ish" rather than "structured". > * often people opened Airflow 1.10 issues even if it reached End-Of-Life in > June (they should open discussions instead - which is still great because > even if there are no way we will handle the issues but either us or other > users can help them still for workaround or even directing t) > > *Discovery* > > Then we discovered that we already can use "Forms for GitHub Issues" (beta > feature but it is available for everyone now - > > https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms > ). > This looked like not only a great way to structure and pre-classify the > issues (by the users) but also seems to be a great communication tool with > the users. We believe it will allow us to address most of the issues above. > Basically instead of committers having to explain the rules over and over > and instruct the users how they should report the issues - it's all there > explained really clearly and nicely while the user enters the issue. > > *Solution* > > We defined forms with required fields that cannot be "skipped". also when > you do not fill a "textarea" entry it is marked as "Not Provided" rather > than deleted. We added helpful comments and hints as well as explanation in > which cases you should use GitHub Discussions (including lack of ability to > select 1.10 version and link to open GitHub Discussions) instead of issues > (with direct link). We've added logo and welcoming message to "soften" the > "more formalized form entry need. We made it clear that if there is no > reproduction steps, the users should open GitHub Discussion instead. We've > added more issue types - we've separated "Airflow Core", "Airflow > Providers" (we have more than 70 providers that extend Airflow's > capabilities) and "Airflow Docs" issues - automatically applying correct > labels, so we do not have to do triage ourselves. We also created a > "maintainer only" issue type with allows to enter pretty much free-form > information (for tasks/todos etc.) and we've added a required "checkbox" to > confirm you are maintainer, to discourage people from using it to raise > their "free form" questions there. We wanted it to be "easy" for committers > to enter such "free form" issue but "not easy" to skip structured > information by the users - at the same time guiding them to use > "Discussions" which are much "easier" to enter any content and ask > questions. > > What is even more - this structured form will allow us to automate some > stuff if we find it is needed. For example if someone submits an entry > without providing "reproduction steps" we can write a bot to automatically > convert such issue into discussion. Or automatically close an issue if > someone opens a "free-form" one while not being maintainer. > > *Demo/Take a look yourselves* > > You can try it yourself here: > https://github.com/apache/airflow/issues/new/choose > > And see some screenshots how our issue form entries looks like: > >- https://ibb.co/Lxgx7xn >- https://ibb.co/0rYqm1Q >- ht
