19:00:08 #startmeeting Ansible Contributor Experience Working Group 19:00:08 Meeting started Thu Nov 8 19:00:08 2018 UTC. 19:00:08 This meeting is logged and archived in a public location. 19:00:08 The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot. 19:00:08 Useful Commands: #action #agreed #halp #info #idea #link #topic. 19:00:08 The meeting name has been set to 'ansible_contributor_experience_working_group' 19:00:16 * felixfontein waves too 19:00:17 #info Agenda: https://github.com/ansible/community/issues/390 19:00:26 #info We define "contributor" as someone that does or should interact with PRs 19:00:28 Who's around? 19:00:59 o/ 19:01:24 I hope more than us three! 19:01:35 Pilou can't make it, becuase "kids" 19:01:37 dsoper2: Hi :) 19:01:40 hello 19:01:40 nod 19:01:51 hi akshay196! 19:02:04 #chair misc felixfontein akshay196 19:02:04 Current chairs: akshay196 felixfontein gundalow misc 19:02:45 hey, I'm lurking, I made it 19:02:57 hi all 19:03:14 agaffney: caphrim007 You around? 19:03:20 #chair decentral1se 19:03:20 Current chairs: akshay196 decentral1se felixfontein gundalow misc 19:03:38 gundalow: aye 19:03:43 woot 19:03:46 o/ 19:03:48 also lurking 19:03:52 #chair caphrim007 acozine 19:03:52 Current chairs: acozine akshay196 caphrim007 decentral1se felixfontein gundalow misc 19:04:27 Cool, will start in a minute 19:06:30 #info As discussed in Contributor Summit in Austin, we'd setup this new group, which I'm working on full time. We are (initially) focusing on PRs, though we are happy to fix other stuff as we go along. It's also expected that some of this work will also improve issues and general community stuff. 19:06:36 #chair sdoran bizonk 19:06:36 Current chairs: acozine akshay196 bizonk caphrim007 decentral1se felixfontein gundalow misc sdoran 19:06:50 Agenda is https://github.com/ansible/community/issues/390 19:06:58 #topic Where to start 19:07:56 gundalow: I'm sort of around 19:07:59 I think we've made great strides with improving the dev docs the way we did. 19:08:13 I have to head out in like five mins to pickup my kid. 19:08:37 #info There is loads to do, and just about anything is "in scope", though based on discussing in Austin we will focus on making things clearer for people, then work on adding more contributors/maintainers/. Part of this group is about "oiling the machine", parts is actually about sitting down and reviewing PRs 19:09:02 there's lots of room for more improvement - especially to the testing docs and the community pages 19:09:05 I think our biggest challenges are 1) Helping new contributors figure out how to navigate our processes and 2) Making sure we are as responsive as we can practically be so folks don't get disillusioned. 19:09:17 #topic Improving Docs: /community and /dev_guide 19:09:26 acozine: sdoran what a great lead into the next topic :) 19:09:27 Because we are burried under the pile and it sometimes takes a long while for us to get to things. 19:10:10 #info Plan for restructure of /community/ and /dev_guide/ https://docs.google.com/document/d/1nMevQ0W7MZgJA1tJrJbNHIhTiHYHYUlO3IHXBs_usGE/edit?ts=5be2cd87 19:10:25 Everybody should have edit permissions on ^, as well as the ability to add comments 19:10:56 Looking at the `Reorganise` section 19:11:13 Thanks to acozine for helping with this 19:11:34 jtanner: hi, we are looking at https://docs.google.com/document/d/1nMevQ0W7MZgJA1tJrJbNHIhTiHYHYUlO3IHXBs_usGE/edit?ts=5be2cd87 19:11:40 #chair jtanner 19:11:40 Current chairs: acozine akshay196 bizonk caphrim007 decentral1se felixfontein gundalow jtanner misc sdoran 19:13:20 This is about making it easier for people to find what's in the existing docs, as well as (subtly) informing people of what else they could do 19:13:42 #info this would be replacement for docs.ansible.com/ansible/devel/community/ 19:14:11 Most of the content already exists, there are a few places I know where we are missing content have been marked 19:15:02 So I'll give you all a few minutes to read the `Reorganise /community` section and add your thoughts in 19:15:06 any initial comments? 19:15:34 I gotta run and get my kid. 👋 19:15:43 curious if module devs actually use these docs or if everyone wings it like me 19:15:44 bye Sam! 19:15:48 bye sdoran 19:16:11 jtanner: good question 19:16:14 i just google when i have questions. i dont think i've ever actually sat down and read any complete doc 19:16:22 other folks: who has actually used the dev guide docs? 19:16:31 I read the docs (about module development) when I started, but nowadays I seldom look in them. I mostly search for something specific which I forgot 19:16:32 i've used pieces of them acozine 19:16:44 caphrim007: yup. and realising that people don't sitdown and read the docs from cover to cover is important 19:16:54 caphrim007: we're hoping to get away from the "here, read this book" approach, as it isn't realistic 19:17:04 or they once did it (like me) but don't notice there are lots of new parts :) 19:17:16 i've read them and found them useful. Mostly module development docs (best practices and purpose come to mind) 19:17:29 We've used them, probably https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_general.html#starting-a-new-module as a starting point for others on our team 19:17:38 i laid out my thoughts about module dev docs here: https://github.com/ansible/proposals/issues/49 19:18:09 acozine: the most recent example I can think of is I wanted to know what the correct yaml content was for deprecating an entire module. I knew it existed, but it didnt pop up as the first result when I googled something like "ansible deprecate module" 19:18:27 i found my answer via a combination of scrolling through docs and github searches 19:18:32 "Old modules may not be what we want people to copy for new modules" - this 19:18:33 infos about deprecation is always hard to find :) 19:18:37 caphrim007: that's great feedback, thanks 19:18:50 yeah, great point. It'd be cool to be keeping an up to date template that new module writers can rely on 19:19:23 felixfontein: yup, I've created a section for deprecation (in green) under `Reorganise /dev_guide/` 19:19:27 I certainly fished around and then ran into a lot of sanity checks and then found the digitalocean module to be more up to date 19:19:36 so copypasta'd 19:19:36 in case anyone finds the meeting minutes because they're looking for deprecation docs . . . here they are: https://docs.ansible.com/ansible/devel/dev_guide/module_lifecycle.html#deprecating-modules 19:19:44 maybe it would be helpful to have a changelog for docs, so you can check what's new without having to go through everything 19:19:56 there are other times (specifically as a contributor) that I will be notified of a change in process only because my shippable run fails 19:20:08 theres a brief period of @##^$@$^ and then i fix it and assume thats the new normal 19:20:11 gundalow: I added that deprecation of specific module option choices would be nice too ;) 19:20:39 https://github.com/jctanner/molecule/blob/MAZER_COLLECTIONS_ANSIBLE_TEST/molecule/command/init/module.py is a prototype of what i wanted to do with proposal 49 19:20:40 At the moment I'm using/abusing https://github.com/ansible/community/issues/346 to notify people of changes 19:21:19 felixfontein: docs changelog is an interesting idea, I'm not sure how we'd implement it 19:21:54 caphrim007: do you have a specific example to give ? (I am trying to see if there is a better way) ? 19:22:02 acozine: maybe a separate page which is just manually updated with a little entry with date, short description and link to changed section. it shouldn 19:22:08 Also worth remembering that most people here are not the target audience for /community/ as you've been through the PR process a lot 19:22:26 't include too simple things (like fixing typos), but no idea where the border would be... 19:22:30 misc: sure when the usage of the "_" variable for non-used returns was changed to...."unused"? is that the one? 19:22:37 I suppose we all know https://towncrier.readthedocs.io/en/actual-freaking-docs/ and friends for auto-change logs? 19:22:46 misc: or when a specific new linter is added 19:22:55 decentral1se: nope, I hadn't seen that 19:23:26 acozine: you can tag your commits and then change logs get generated. If you submit a docs issue, ansibullbot could make sure you've added a commit tag or something 19:23:44 anyway, might be something to look into for docs related change log 19:24:01 Thanks decentral1se, I'll experiment with that a bit 19:24:02 caphrim007: new linter, I guess this could be announced, but then I guess the problem is maybe that people do not run linter locally, cause if people got in the habit, it might be faster 19:24:25 coooool 19:24:49 misc: i dont run the test locally. i just push to shippable. every time i've run them locally they've ended up passing and then failing in shippable 19:24:54 so i just punted and used shippable 19:24:57 maybe ansibot could watch the test result and react by saying "this error is caused by this new stuff, here is what you need to know" ? 19:25:26 misc: well, by that point in time i've already seen the error and corrected it 19:25:45 acozine: I think there is also https://docs.openstack.org/reno/latest/ which was recommended recently 19:25:49 if i were able to correct it before i submitted the pr, then i think it would be valuable, but if its only after shippable fails, then "meh" 19:26:00 reno is similar to what we use today 19:26:32 the tests should also fail locally, but you'd need to rebase first 19:26:55 #action acozine gundalow to think about changelog for docs, test infrastructure, coding standards 19:27:04 That's good feedback thanks 19:27:09 So back to the Google doc 19:27:15 oh, didn't know, cool 19:27:25 so the sequence should be: 1. make changes 2. rebase branch 3. run tests locally 4. open PR 19:27:41 5) rebase and test before pushing new commits 19:27:53 So a lot of this, especially `/community/` is aimed at New Contributors 19:28:19 yeah, so the docs need to start with the basics 19:28:45 And that's where I'd like us to focus initally 19:29:42 1) Do people like that /community is broken down by `Getting started`, `Getting more involved`, `Making more contributions`? 19:29:47 Does that make sense? 19:30:11 Yeah, I like it 19:30:11 Is the content in the right section 19:30:19 What's missing 19:30:25 even if I am not sure what is the difference between the 2 19:30:28 3 19:30:57 how do I know if I need to read the 3rd or just the 2nd ? 19:30:58 misc: it's intended to be Beginner, Intermediate, Advanced sections 19:31:09 so clearly, they need better names 19:31:13 :) 19:31:24 it's the third one that has stumped me 19:31:29 well, maybe divide by the duration ? 19:31:35 Getting Started and Getting More Involved make sense 19:31:43 but what's Level 3? 19:31:47 or like "how do you first PR, your 10 first PR and after ?" 19:31:56 how to become maintainer? 19:31:57 :) 19:31:58 "Making more" is about developing, so maybe reword level 3 19:32:13 misc: that's a fun idea 19:32:37 felixfontein: `What are maintainers and how do I become one?`is a heading under `Making more contributions` 19:32:51 We were not sure if maintainer should be a top level section or not 19:34:00 I also wonder how much showing "maintainer" as the ultimate evolution (kinda like pokemon) is not going to push people to be coder while we are also trying to get folks for others stuff (doc being a example) 19:34:08 does anyone else think 'maintainer' is a word that has a dreaded murky connotations behind it? 19:34:27 decentral1se: I hadn't till you mentioned it 19:34:32 yeah, we want to emphasize that writing code is not the only way to contribute 19:34:56 decentral1se: what connotations do you hear? that it's scutwork? 19:35:09 #agreed Writing/reviewing code is only one way to be a contributor 19:35:15 yeah, you're in, you're stumped, long haul, janitor, lonely, etc ;) 19:35:25 collaborator has a bit more flair to it 19:35:28 cooperator 19:35:30 I like the emphasis on other ways to contribute, with level 3 focusing on development/I want to write a module 19:35:39 yeah, collaborator has its own linguistic baggage 19:35:42 I dunno, shooting from the hip now ... 19:35:59 Joining the Cabal? 19:36:01 I like collaborator less than maintainer 19:36:30 maybe "expert" or some variant of that/ 19:36:48 So it's OK for people to not progress to the next "level" 19:36:57 mhh, wouldn't it attract too much people for the fame and the title ? 19:37:18 heh 19:37:38 ok, lets view about what they are doing 19:37:39 (that's a real issue we did had in Fedora :/ ) 19:37:52 LEVEL1: reading stuff, chatting on mailing list 19:38:18 LEVEL2: Reviewing stuff, reporting bugs, requesting features 19:38:28 LEVEL3: Contributing PRs 19:38:37 LEVEL4: Maintainer 19:38:47 Is that what people are thinking? 19:39:01 (with care that L3 isn't just about contributing code) 19:39:16 I wouldn't place reviewing in that order 19:39:42 because we likely need more reviewer than PR 19:40:16 Though if people stop after L2, that gives us more reviewers 19:40:18 so if we keep the idea of progression, people doing review would see that PR is the next step, while I think it is our best interest to have them do review 19:40:41 Maybe that's fixed by putting some wording at the top 19:40:46 so maybe maintenr as 5, and review as 4 ? 19:40:50 PR authors hopefully also do reviews :) 19:41:06 We can get people to do review that have never contributed a PR 19:41:08 misc: +1 19:41:11 wish i could pay more attention here, but things are so busy 19:41:36 I think L5 is understanding the process so you don't get burned out on lacking interaction or lost in world scale amounts of organisational churn 19:41:37 jtanner: everything will end up in the Google Doc or GitHub issues 19:41:41 or you stopped caring but are still around ;) 19:41:41 maybe we need a diamond diagram, with PRs and reviews on the left and right side, maintainer at the bottom, and level1+2 at the top 19:42:05 OK, maybe we should leave this bit and give people time to think on it 19:42:06 L2 is pretty dangerous in that regard. Easy to drop off, as mentioned by acozine above 19:42:55 #info How can we make it clear that if "all" someone does is review PRs that's great (and in someways better than contributing new_modules) 19:43:25 #info Can we do some diamond diagram to show this? 19:43:29 credit people in changelog ? 19:43:39 webknjaz is a prolific reviewer 19:43:42 get a list of the people who did most review or something ? 19:44:08 wasn't there this funny guy some months ago who "reviewed" random PRs? I guess he would have won... 19:44:33 someone spammed heart emojis 19:44:40 #action create issue for tracking ideas on how to motivate reviewers. credit people in changelog, points/badges/stars - watch out for people gaming the system 19:45:04 is there a review group? If you're doing it alone, no matter how much the docs tell you how great you are, it might not be motivating 19:45:08 callouts by release for people that did a lot of "things" is probably a good target 19:45:09 OK, at this stage I don't want to get into this. before we encurage more reviewers I want to make it clear what reviewers need to do, and how to do it 19:45:48 if someone undertands my level of involvement and knows what I might be able to review, that'd be great 19:45:56 imo, code style is pointless and should be automated as sanity/linting tests 19:45:58 curating what is being reviewed ... maybe there is just not enough hands on deck for that 19:46:12 OK, lets move onto reviewing 19:46:13 L2 is some cases would be "Ansible isn't working correctly/like I need", would be good to tie bug reports/feature requests back to the review process 19:46:39 #topic Improving Docs: How to Review and test a PR 19:46:51 #link https://docs.google.com/document/d/1nMevQ0W7MZgJA1tJrJbNHIhTiHYHYUlO3IHXBs_usGE/edit?ts=5be2cd87#heading=h.kzxzqyez5fp5 19:46:59 imo reviews should be helping folks make better use of APIs or optimization or indicating usefulness of code 19:47:01 #info See the `[Docs] How to review & test a PR #399` section 19:47:50 So, as I mentioned above I think the docs that explain how to review; what we want from a review; how to give feedback are lacking 19:49:06 #info During Contributors Summit in Austin we identified that we don't have any clear guidelines on how to do local testing of a PR 19:49:50 maybe this would help? https://github.com/jctanner/jfc/blob/master/examples/site.yml#L9-L14 19:50:38 I believe `pip install git+https://github.com/ansible/ansible.git@refs/pull/PR_NUMBER/head#egg=ansible` gives you a rebased branch 19:51:10 So I think there are two (main) types of PR 19:51:11 oh, nice trick 19:51:14 assuming you are going to test the branch in it's entirety 19:51:27 rather than just try out the modules 19:51:34 1) a single module (new or update), so you can just drop it in `library` 19:51:46 2) Something more complex, that requires you to run from branch 19:51:53 s/module/module-or-plugin/ 19:52:15 We have interest in people testing PRs/reviewing docs who aren't really able to do a code review, so ways for someone not too familiar with git/python/etc. to just get the module in the PR and test/review updated docs 19:52:18 If that's right, is it "just" a case of documenting those two workflows 19:52:32 dsoper2: I believe we do 19:52:37 the vmware stuff is especially nice to have people say "works for me" 19:52:40 and I believe with some guidance we can get more 19:53:25 One review from someone that's actually *used* the module, is worth 398 reviews pointing out better ways to do things in Python, or add/remove capital leters 19:53:36 agree 19:53:37 yeah 19:53:42 gundalow: +1 19:53:59 And as part of this I want people to say *how* they've tested it (not just `shipit`) 19:54:00 OK 19:54:19 could it be useful to have people volunteer to be pinged to test specific module ? 19:54:23 so I wonder if in the "draft of wording" we can collectively flesh something out 19:54:27 kinda like maintainer, but for testing ? 19:54:39 misc: possibly, though for the moment, I want to get docs that explain how to do this 19:54:42 then we can add peopl 19:54:49 gundalow: yup, first things first :) 19:54:51 hum, I need to document my bigger plan somewhere 19:55:35 #action gundalow needs to document his bigger picture plan (contributor workflow, why we are starting with docs before adding people. Why we improve the SIGs before adding people) 19:55:35 do the working groups with a product focus (vmware, etc.) do regular PR triage in their interest areas? 19:55:37 OK, so to the docs 19:56:00 DING DING five-minute bell 19:56:05 acozine: Thanks 19:56:16 OK, lets spend the last five minutes on teh docs 19:56:28 multiplayer doc writing time 19:57:02 we're writing things in that google doc? 19:57:07 Yup 19:57:19 right at the bottom, `Draft of wording` 19:57:54 perhaps "works for me" + -vvvv output? 19:58:27 sigh, i think i'm slow 20:01:45 Moved `What type of feedback we want` down to `How to test` 20:05:52 misc: I wonder if `could it be useful to have people volunteer to be pinged to test specific module ?` is just a maintainer 20:06:11 Ok, that's the hour 20:06:18 gundalow: misc: maintainer's posse? 20:06:37 gundalow: yeah, but a maintainer is expected to do more, like review, approve, code ? 20:06:56 I guess there could also be maintainers which only cover a subset 20:07:04 but yeah, maybe I am complciating thing too much 20:07:14 like knowing exactly how the module reacts / should react and thus being able to test, document, and give good feedback 20:07:23 misc: hum, If they run the module and it works, is that a better reason to merge than saying the codes a bit funky? 20:08:36 Unless we extend the bot to know about `shipit:runit` `shipit:readythecode` I'm not sure what breaking down maintainers into subgroups would do 20:09:07 so, would we take anyone who volunteer to be maintainer ? 20:09:51 We'd need to think about it more. Not like we currently give maintainers a codeing tests, or check they've written (good) modules 20:09:54 what do you mean by "anyone"? they should demonstrate some kind of knowledge of the module :) 20:09:58 yep 20:10:02 +1 20:10:48 I have to run - see y'all 20:10:55 well, the idea is that people who are volunteer to test get notified, and that we can use that to know how popular a module could be. I do not think having 50 maintainer of a module is realist, but having 50 potentials users could be ? 20:10:57 acozine: Thanks for your time 20:11:08 oh, I see 20:12:00 my idea is inspired by Fedora, there is people dealing with rpms, specs files, and people testing them in update-testing. I think there is a potential to bridge the gap between "I use Fedora" and "I do maintain a package" by "I test this specific package when I have time" 20:12:06 and so the same for modules 20:12:32 except we do not have the workflow in place for now, and maybe that's not a worthwhile complication given the compared scale 20:12:43 (but could be if modules are moved to galaxy I guess) 20:12:47 oh, then there is the rpm votey think were you need to get +n votes over an x-week period 20:13:03 yep 20:13:20 totally different from the shipit we have where you need to get 2 of them 20:13:36 like, not the same number, in 1 case, you need 3, and the other, you need 2 :p 20:14:26 So longer term, maybe we'd link to issues/PRs from the doc site 20:14:35 or have an "adopt a module" program 20:15:06 with cute dog pictures \o/ 20:15:09 :D 20:15:14 why not cats? :p 20:15:17 (or cute cat, not going to start a flamewar) 20:15:22 lol 20:15:27 cow(say) 20:15:29 anwyays 20:15:37 #topic the high level plan 20:16:27 So, I need to actually write this down, though it's basically 20:16:40 * Think of the PR process 20:16:53 * Think of what is needed to progress a PR from one stage to the next 20:17:13 * Do people know how to do ^, is it documented, is it clear what stage a PR is in 20:17:23 spoiler alert: no and no 20:17:46 :) 20:18:11 * improve docs for this 20:18:27 * simplify the process - remove edge cases 20:18:43 I got a cluster headache trying to draw out the PR approval process 20:19:18 * watch people go though this process and ask what was confusing - see Speak to new_contributors https://github.com/ansible/community/issues/353 20:19:56 * Once we've reduced the chance of people asking "what do I need to do", we can they look at ways of adding more people in 20:20:13 +1 for asking 20:20:43 Reason I don't want to add too many people yet is: It's a bit crappy if they get all excited and motivated ask how to test a PR, and I go urrrrrrrrgh, soz, need to write some docs 20:21:25 likewise ensure all the Working Groups have a defined list of things (and not just Python things) to do, *then* we can promote the Working Groups 20:22:03 That's a my rough plan of attack that I've had in my mind for a while 20:22:30 sounds good! 20:22:36 Hope that makes sense 20:24:06 it does 20:24:10 woot 20:24:15 anyways, it's late now 20:24:19 and ever later for you misc 20:24:27 well, that's ok 20:24:29 * gundalow forgets where in the world felixfontein is 20:24:36 Switzerland 20:24:36 (except the part where I am hungry) 20:24:50 Thank you all for your time today, this has been really useful to me, and I hope to you 20:25:09 misc: we just finished dinner before the meeting started ;) 20:26:00 #action gundalow to do walkthough and document how to test a PR 20:26:07 Thanks again y'all 20:26:09 #endmeeting