14:05:43 #startmeeting Ansible Docs Hackathon 14:05:43 Meeting started Tue Jul 7 14:05:43 2020 UTC. 14:05:43 This meeting is logged and archived in a public location. 14:05:43 The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:05:43 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:05:43 The meeting name has been set to 'ansible_docs_hackathon' 14:06:02 woot woot! 14:06:07 #chair acozine samccann felixfontein resmo 14:06:07 Current chairs: acozine felixfontein gundalow resmo samccann 14:06:30 We've got multiple ideas for docs help over on https://etherpad.opendev.org/p/virtual-ansible-contributor-summit-july-2020 14:06:39 (scroll down to the July 7th hackathon list) 14:06:53 * gregdek hullos 14:07:09 * samccann digs up something special for gregdek to fix 14:07:13 ;-) 14:07:22 #chair gundalow gregdek 14:07:22 Current chairs: acozine felixfontein gregdek gundalow resmo samccann 14:07:35 Oo! 14:08:20 gregdek: are you drunk with power yet? 14:08:42 I try not to get drunk with power until after noon. 14:09:05 power is a nice guy, but he does not keep top shelf in his bar 14:09:23 ok, what's the plan? 14:09:28 sure she does.. right behind the 'don't let bcoca see the good stuff' sign 14:09:32 heh 14:09:32 * bcoca is making mojitos 14:09:55 drink coding is not a law infrightment ? 14:09:55 my nickel is we start with 'what does gundalow want' 14:10:08 s/drink/drunk/ 14:10:11 aka the first time on the list - moving prs/issues 14:10:29 baptistemm: in some cases, sober coding is the infringment 14:10:31 samccann: haha, I approve 14:11:23 #topic Docs to help understand moved issues/prs 14:11:41 #info reviewing the last comment here to generalize - https://github.com/ansible/ansible/pull/70488 14:11:42 I started updating the main RST docs to reflect collections - https://github.com/ansible/ansible/pull/70488/files is my first look at the Community pages, which have not had much attention paid to them recently 14:11:55 Can I just ask a bunch of rambly questions of people? Is that ok? 14:12:01 gregdek: ramble away 14:12:13 * samccann munches morning popcorn and waits for the ramble 14:12:33 So I think there are a few related things here 14:12:33 1) Directing people where to go (ie, how to find the repos) 14:12:33 2) Guiding people on how to do Collection development (assuming they knew gh/ansible/ansible development) 14:12:33 3) Drafting some text that the bot can add on gh/a/a that links to `1` & `2` to help people understand 14:12:54 OK, rambly question 1: is core already moving or redirecting issues, and how are they doing it? 14:13:14 how: bot 14:13:44 gregdek: see https://github.com/ansible/ansible/issues/70493#issuecomment-654688903 for example 14:13:44 Is the bot closing with a pointer to the new repo, or closing with a "find the repo" game? 14:14:16 Ah. So that's mkrizek. Is that a manual process, then? 14:14:19 #info need to direct people where to go (new collection repo), guide them on how to develop collections, and draft text for a bo to add on ansible/ansible that links to these two items to help people understand 14:14:49 afaik it's manual until we do what gundalow sez above. then a bot can have at it 14:15:03 gregdek: all the ones I'm finding are manual, see https://github.com/ansible/ansible/issues/70489#issuecomment-654567958 for another example 14:15:07 OK, so bcoca, are there some issues that are bot driven? 14:15:20 Or were you saying you aspire for them to be bot driven? :) 14:15:44 gregdek: are/will be, most of the redirection of tickets in ansible/ansible to collections will be/are handled by bot using galaxy data 14:15:51 gregdek: Currently the Bot adds `label/needs_collection_redirect` and one or more `label/collection:community.general` labels, ie https://github.com/ansible/ansible/issues/69679 14:16:05 So it looks like in the first case, mkrizek pointed them to the new repo to file and issue, and in the second case, akasurde actually moved the issue for them -- is that right? 14:16:11 ^ at one point we'll switch to closing those issues 14:16:28 gregdek: no, we will try to avoid humans doing it 14:16:50 Ok, so the current process is roughly (1) label gets added, (2) humans triage and move/close? 14:16:53 Is that right? 14:17:06 or 'do nothing' so bot will take care of it later 14:17:06 here's the bot comment: https://github.com/ansible/ansibullbot/blob/master/templates/collection_migration.j2 14:17:14 yes, though once we are happy (2) will be done by bot, using ^ template 14:17:27 the bot comment looks like it's ready when we are 14:17:44 we are mostly waiting to be happy with 'bot accuracy' 14:18:10 Are we doing the same with PRs? 14:18:43 gregdek: yup, exactly the same process for PRs 14:18:47 no distinction 14:18:57 # info bot will add the following comment to closed issues/PRs - https://github.com/ansible/ansibullbot/blob/master/templates/collection_migration.j2 14:19:13 samccann: need to remove space 14:19:20 heh 14:19:28 Is everyone ok with the bot copy? 14:19:32 #info bot will add the following comment to closed issues/PRs - https://github.com/ansible/ansibullbot/blob/master/templates/collection_migration.j2 14:19:45 bot copy points to an .md file. 14:19:51 * acozine looks at the link it's pointing to 14:20:03 So I assume we should update that file with the links gundalow requested at the start of this meeting 14:20:04 I approve that https://github.com/ansible/ansibullbot/blob/master/templates/collection_migration.j2 doesn't actually contain much info as it's impossible to change later. 14:20:12 Because it seems like this process is basically fine and works-ish, and will be improved in the future with the bot, and corner cases will get triaged as needed, and people are being directed to the right places? 14:20:39 And perhaps the only question is what copy we want in that template, exactly? 14:20:42 for some definition of 'right' 14:20:47 Heh. 14:21:18 this assumes a) colleciton is on galaxy b) there is repo info in galaxy c) there is actual public repo accessible to users 14:21:23 Should we vote on if we are fine w/ the bot comment? 14:21:36 gregdek: bot template should be smallest amount of text. Need to remember that it might be a day or a year(s) till someone reads it and acts on it. 14:21:36 Therefore we can't change that text 14:21:47 at a minimum we should include the "Contributing to Ansible-maintained collections" as a link on that markdown page 14:21:53 I disagree 14:21:59 https://github.com/ansible/ansibullbot/blob/master/docs/collection_migration.md <- is where the work needs to be done 14:22:00 oh sorry i agree hehe 14:22:32 gundalow: either that, or we move that content onto an rst page and change the link to point to the content there 14:23:01 i vote to leave it as the md for now 14:23:07 Just so the first interaction is simple, polite, and provides clear next steps for remedy, I think it's fine. 14:23:22 acozine: sure, I'm happy for https://github.com/ansible/ansibullbot/blob/master/docs/collection_migration.md to move elsewhere. Thought not a `/latest/` link as they needs backports 14:23:24 i can so totally see Future Me modifying an rst file, forgetting what is pointing to it 14:23:38 I'd like us to get the location of the file right first time 14:23:50 samccann: leave comment in rst that tells you 'what points here' 14:23:52 whereas the .md file is off on its own, so we won't mistakenly update it 14:24:41 bcoca: +1 14:24:57 yes, but I'm also in favor of keeping docs in the repo that relfects it, in this case, keep it in ansibullbot 14:25:21 s/relfects/reflects 14:25:56 not a hill i'm willing to die on, but that's my thought process on this one 14:26:12 POLL: Are we happy with the text in https://github.com/ansible/ansibullbot/blob/master/templates/collection_migration.j2 (ignoring the fact that the linked guide may move location) 14:26:15 +1 14:26:28 +1 14:27:08 +1 14:27:09 * bcoca is never happy, so can be ignored in this case 14:27:17 heh 14:27:47 https://github.com/ansible/ansibullbot/pull/1389 14:28:28 thanks for that! 14:28:45 +1 14:29:51 samccann: I agree about documenting bot behavior in bot docs 14:31:26 so looks like we are fine with the comment. Next decision is to keep the docs in the bot repo or move them to .rst? 14:31:42 could stay in the repo *and* be RST 14:31:52 ugh 14:32:10 that leaves two place to track in case someone makes a change in either 14:32:35 gundalow: about https://github.com/ansible/ansibullbot/blob/master/templates/collection_migration.j2 I would add a small text before why the file were migrated (I like to give the Why) like "Ansible repository was split in several repositories" 14:32:41 I'd rather we for example, mention 'migrated issues/prs' in .rst with a pointer to the bot docs... or move the bot docs into rst 14:32:48 * baptistemm is lagging due to $ work day 14:33:23 or even linking to a announce on the google group 14:33:56 I have to drop to talk to a recruiter, I'll be back in ~30 14:34:05 ok thanks gundalow ! 14:35:31 so for someone completely unaware of the haps in ansible land, yes, it would help to have a short sentence to say ansible/ansible split into multiple repos. 14:36:40 should we get rid of the markdown page and just put that content directly in the comment? 14:37:08 hm, it's a bit long for that 14:37:11 yeah 14:37:21 but maybe put the first paragraph and the links into the comment? 14:37:31 and leave the rest of the FAQ in the markdown? 14:37:39 that would be fewer clicks 14:37:45 I think it can be easier than that 14:38:15 just modify the first sentence to say why. 14:38:32 I always favor more clarity in the actual issue, even if some think it's a bit wordy... 14:38:43 I know others disagree :) 14:38:49 (some others, anyway) 14:38:56 other others 14:39:11 there is ballance between clarity and longevity in this case 14:40:33 As much clarity as possible in the short, with a link to the longer explanation for those who need it, I suppose 14:40:33 "Thank you very much for your interest in Ansible. Ansible has migrated much of the content into separate repositories to allow for more rapid, independent development. We are closing this issue/PR because this content has been moved to a separate collection repository." 14:40:46 wfm 14:40:50 +1 14:40:56 (with link to more info I assume) 14:41:20 same link below, from which the user can follow links to the blog post and/or the docs pages 14:41:43 back 14:41:46 1 14:41:53 gundalow: that was a quick 30 minutes! 14:42:00 acozine: indeed 14:42:27 acozine: they were very efficient 14:43:01 ok should I add that sentence to the bot in a pr? 14:43:01 `"Thank you very much for your interest in Ansible. Ansible has migrated much of the content into separate repositories to allow for more rapid, independent development. We are closing this issue/PR because this content has been moved to a separate collection repository."` +1 14:43:14 ok doing that now 14:43:21 hooray! 14:43:21 As long as the bot template doesn't contain any of the technical info, or guidance then I'm OK with that 14:44:01 my point was not about technical but giving a bit more of context so I'm good with the sentence 14:44:09 +info 14:44:34 And then we do point to the correct repository as best we can, right? 14:44:50 I think that's what the bot code is doing? 14:45:07 (in that comment)... but you know, take my coding skills w/ a grain o salt 14:45:58 https://www.irccloud.com/pastebin/DtRpPf0i/Code%20pointing%20to%20repo 14:46:15 gregdek: ^^^ 14:46:25 Just making sure :) 14:46:37 it's trying, we won't know how successfully until we set the bot loose 14:47:04 PR to update the comment - https://github.com/ansible/ansibullbot/pull/1390 14:47:40 I think we can modify the bot to only close a subset of issues&PRs. Brad suggested we run it against `label/networking` 14:47:58 I like `label/collection:community.general` to be the last that it runs against 14:48:00 I don't know what's behind collection_file_matches so can'thelp 14:48:57 ah so to gregdek's point - the code looks to come up with the collection name, not a link to the actual repo so to speak. So that's detail we'll need to add into the .md file "how to find the repo for the collection" 14:49:59 If we could transmogrify the code to point directly to the right repo, that would be ideal, but I don't know if that's tricky for some reason 14:52:00 stan_g: hi and welcome 14:53:07 I think the issue is that Galaxy doesn't have an API to return Repo for a given location. Also repos can move 14:53:53 So therefore I don't think the Bot can put a link in, though we can (and MUST) detail how to do this lookup on the separate page 14:54:11 Galaxy allows for (but does not require IIRC) links for `Repo` and `Issue tracker` 14:54:58 could the bot link to the collection in galaxy, wherein there may be links to repo/issue tracker? 14:55:22 I 'think' the url is predictive 14:57:16 Hmm 14:57:37 oh, yes, we can do that `galaxy.com/NAMESPACE/COLLECTIONAME/` 14:58:15 Need to split FQCN on `.` then build the link here: https://github.com/ansible/ansibullbot/blob/master/templates/collection_migration.j2#L4 14:58:16 Perhaps the ideal is "point to the specific issue tracker URL if it exists, and if it does not, point to the Galaxy collection instead", but then I don't know if we're torturing macros beyond their ability 14:59:08 But really, if it's a core redirect we're talking about, we can simply declare that repo URL must exist to be accepted into Ansible. Which I think is actually a thing we should do! 14:59:43 "If you're going to be included in Ansible, you must be open for issue tracking and PRs" sounds a sensible policy to me. 15:01:09 hi, i'm a bit late. sorry. quick question: what are you going to do, to close all collection related issues/prs in ansible/ansible? will they be open in correspoinding collections (i.e. moved) or just closed in ansible-base and people should copy them manually if they are interested? 15:01:31 Hey andersson007_ :) 15:01:59 hey gregdek ! 15:02:00 I believe the goal is to close them with an appropriate redirect message, and we've been discussing how to create that appropriate redirect. 15:02:11 andersson007_: Generally speaking, we will not recreating new issues 15:02:23 andersson007_: welcome! we can't move most of them because GitHub doesn't support moving across namespaces/orgs 15:03:04 ok, clear, makes sense. to get rid of abandoned probably irrelevan stuff 15:03:22 So thinking out loud here. These are issues or PRs open on Ansible that reflect(ed) what used to be in Ansible. Is there any situation wherein that content moved to a collection that doesn't have a repo in ansible-collections? 15:03:26 the originals were in ansible/ansible; the new ones (mostly) belong in ansible-collections/coll_name 15:03:57 samccann: some collection are not in ansible-collections like openstack I think 15:04:21 Yes, not all collections are in ansible-collections, most but not all I believe, gundalow can check me on that 15:04:26 it is https://github.com/openstack/ansible-collections-openstack 15:04:26 ok but to greg's point - it's still an open repo. Nothing moved out of Ansible into a closed repo 15:04:40 Yes. They should all be open repos, we can require that. 15:05:05 gregdek: x2 with partners, last i looked, not all were using open repos (but its been a while since i checked) 15:05:07 Which means that we should safely be able to pull the issue tracker URL from the Galaxy API. 15:05:18 If they want to be in Ansible, we can simply tell them to do that. 15:05:22 also, many published collecitons were missing repo info 15:05:25 The power of upstream. :) 15:05:28 if the API supports it, yeah (Galaxy api) 15:05:38 galxy supports it 15:06:21 only issues is making it a requirement and enforcing such requirement 15:06:40 s/is/are/ 15:06:50 Right, dunno how we can gate that, and it sounds like maybe we've got some collections already built that don't have that, sigh 15:07:42 ok then back to updating the bot to give the galaxy url? 15:08:00 gah... are all migrated collections IN galaxy yet??? 15:08:27 if not, then we are back to what the bot does today and putting how to find the repo in the docs 15:08:27 no 15:09:19 * samccann grumbles something my mum said about 'best laid plans of mice and men' 15:09:42 :) 15:09:48 so collections aren't in galaxy yet and we don't necessarily want to wait on turning the bot on until they are, correct? 15:09:55 or do we? 15:10:03 What's the best thing we can do for the long term, knowing that it won't be perfect in the short term? 15:10:07 is the bot a cleanup so we can stop looking at old issues/prs? 15:10:20 or to direct people in limbo on how to move forward? 15:10:26 Can we have the bot handle only those issues that have known issue repos, and then put others in a triage state? 15:10:34 This is my suggestion for a "belt-and-suspenders" approach, but I'm not sure what to tell folks to do when the comment is missing https://www.irccloud.com/pastebin/PiGUzW9e/Proposed%20text%20for%20new%20question%20on%20markdown 15:11:25 oh, wait, will the link be to GitHub or to Galaxy? 15:11:31 if the link is missing, the collection isn't on galaxy (assuming the bot is updated to point to galaxy) 15:11:38 I think that's what we're still trying to sort out :) 15:11:42 heh 15:11:59 A lot of it is, what's possible with a reasonable amount of effort? And that's a thing I don't know. 15:12:16 ok so first question for me - are we urgently needing to turn on the bot before, say, 2.10 releases in a bit over a month? 15:12:26 I think not. 15:12:36 I mean, it seems like Core already has a triage process. 15:12:36 then the collections MUST be on galaxy by then, right? 15:12:56 Yes, or they've missed the bus. 15:13:23 so my nickel - use the galaxy url and have something in the code to detect if it doesn't exist, just post the collection name 15:13:41 * samccann finds joy in stating things she hasn't a clue how to implement 15:13:55 I'd like to do it that way, but I don't know the effort. gundalow or abadger1999 could say better. 15:13:56 and then not turn the bot on until at or about 2.10 release 15:14:31 ah yeah, the code may not be able to determine if the galaxy url exists or not. 15:14:31 Assuming the core team is still available to triage, none of this is a blocker, it's just (very) nice to have. 15:14:55 Right, I don't know what calls the API where/when. 15:15:01 but then acozine's note could say something like 'if the url doesn't exist, please do x, y, z to find the collectoin' in the docs 15:15:19 ah ok.. the API. So that was the other idea 15:15:50 use the api to get the issue tracker link directly (a better idea) and if the api returns null or whatever (aka collection isn't on galaxy) then print out the collection name 15:16:02 * samccann still finding joy acting like she has a clue how the code could work) 15:16:07 the bot would have to cache the data but it should be possible to query the galaxy API for it. 15:16:31 * abadger1999 restarts firefox since every line he types has several seconds delay. 15:17:04 gregdek: we are missing ~4 collections from galaxy today 15:17:43 gregdek: for new issues, manual triage might work, but the collections migration gives us a great opportunity to clear the backlog 15:18:01 ok, my time is up. Sounds like we're in a decent place, just figuring out how to get to a better place, hope the ideas/thinking were helpful :) 15:18:04 * gregdek wanders afk 15:18:09 gregdek: 37 out of the 58 collections are under gh/ansible-collection 15:18:09 heh 15:18:13 gregdek: thanks! 15:18:56 so my nickel - get the bot to find the issue tracker and use that link. if the collection isn't on galaxy, just print the collection name or whatever it does now. 15:19:14 and pospone turning it on until those final 4 collections get into galaxy 15:21:49 didn't someone say we could turn the bot on for limited collections? 15:22:21 that was a suggestion, yeah. So that's a good idea. Get it updated, then turn it on networking (but only if community.network is already on galaxy) 15:22:43 Oooohhh... issue tracker... I wonder if galaxy makes that available in its REST API. 15:22:44 acozine: That's what I'd like to do. Will take a little bit of Bot work. Though I'm not happy to spam everybody at one go then realise "duh, the guide isn't clear about how to do X" 15:22:44 or I should say that one of the 4 missing collections isn't network related :-) That would be a good trial run 15:23:03 abadger1999: I think bcoca said issue tracker is in the galaxy API, yes 15:23:14 https://galaxy.ansible.com/community/network 15:23:49 ok we've strayed out of docs land for sure, but what is our next step on this one? Do we open an issue on the bot with this recommendation? 15:23:52 It does not. 15:23:58 DAG NAMMIT 15:24:05 So we would have to screenscrape to get it. 15:24:29 well, the other option was to create the galaxy url based on the collection name since it's predictive 15:25:14 and again, not turn the bot on except for labels like network where we know it's all on galaxy now. 15:25:20 I think a PR to update the template would be good 15:25:26 then we can wordsmith in there 15:25:51 oh...hmm... someone here have the knowhow on how to update the template to create the galaxy url? 15:25:55 did we decide if we were keeping the other file as `.md` (or `.rst`) in the current repo)? 15:26:10 we got down a rabbit hole and did not decide that yet 15:27:22 time to VOTE 15:27:41 heeeek /me was away 15:28:16 POLL: We update the bot template to produce the galaxy url and then update the docs (wherever they live) to explain how to find the repo from that link 15:28:24 +1 15:28:26 +1 15:28:27 +1 15:28:59 #chair 15:28:59 Current chairs: acozine felixfontein gregdek gundalow resmo samccann 15:29:16 ok that might be the only folks we have around 15:29:18 how do we unchair greg? 15:29:18 (repo is in the galaxy metadata [assuming it was in the collection metadata] issues are not) 15:29:25 #chair abadger1999 15:29:25 Current chairs: abadger1999 acozine felixfontein gregdek gundalow resmo samccann 15:29:32 #unchair gregdek 15:29:32 Current chairs: abadger1999 acozine felixfontein gundalow resmo samccann 15:29:34 I don't believe you can unchair. 15:29:36 hah it worked! 15:30:03 TIL 15:30:12 got a vote abadger1999 baptistemm ? 15:30:29 no as I did not read the backlog 15:30:34 I haven't caught up with reading yet but I suspect +1 15:30:52 * baptistemm +1 abadger1999 decision 15:31:07 I'm happy to help in any case 15:31:08 lol 15:31:16 I need to leave 15:31:18 I'm gonna use that everywhere now 15:31:25 ok thanks baptistemm !! 15:31:27 are other folks around? andersson007_ awcrosby briantist bvitnik cbudz cyberpear madonius persysted Pilou resmo shaps stan_g 15:31:30 "I haven't caught up yet but I suspect +1" 15:31:34 heh 15:31:48 ciao baptistemm 15:31:51 oh, I was thinking of borrowing the "+1 whatever abadger199 sez' 15:32:02 add 9 ^ 15:32:20 ok gonna close out the poll 15:32:53 +1 15:33:06 #agreed We update the bot template to produce the galaxy url and then update the docs (wherever they live) to explain how to find the repo from that link (3/0/0 and 2 potential +1) 15:33:16 heh thanks resmo ! 15:33:31 Excellen 15:33:33 t 15:33:33 anytime ;) 15:33:41 Ok with that decided, the next debate - do we keep the docs with the bot or move them into .rst on docs.ansible.com 15:33:52 is ther a way to run a dry run of the bot somewhere ? 15:34:01 keeping it with the bot has the pro of keeping the docs in the same repo as the bot 15:34:16 in order to know what it will look like before ruinning it on all PR ? 15:34:34 baptistemm: the thought is to run it on the network label first, once it's ready 15:34:58 we could look at the "PRs/issues by file" page and find something with only a few entries 15:35:03 afaik the network team volunteered :-) 15:35:19 they are brave! 15:35:36 but yeah, if we have a smaller label test we could run, that would also work 15:35:37 * resmo was informed by monitoring that gitlab pages are down 15:35:48 meanwhile - md or .rst? 15:36:18 with the caveat of wherever we put the docs, it STAYS there since the bot will link to that location 15:36:55 resmo: yikes, that's not good 15:37:18 this is what the md file says today to give y'all an idea of the content of said docs - https://github.com/ansible/ansibullbot/blob/master/docs/collection_migration.md 15:37:46 POLL: +1 means we keep the explanation of the GitHub comment as a markdown file on the Ansibot repo (https://github.com/ansible/ansibullbot/blob/master/docs/collection_migration.md) 15:38:22 +1 15:38:29 -1 means we move that content elsewhere (probably an rst file) 15:38:39 ^^^ was not my vote, merely an explanation 15:38:57 * acozine hasn't done enough polls yet 15:39:02 +1 15:39:24 because I like documenting the bot's behavior in the bot's own docs 15:39:30 same for me 15:39:52 Time to rattle the chairs again? :-) 15:40:05 not for me, I am here ;) 15:40:42 :-) got a vote? 15:40:53 I am kind of -1-ish 15:41:06 got some thoughts to share on that? 15:41:37 * resmo yeay, gitlab pages up again. 15:42:24 resmo: phew! 15:42:57 so what's your thinking on moving the content about "why is my PR/issue being closed"? 15:44:07 cause i wanna! 15:47:49 heh 15:47:58 +0 I'm pulled in both directions. 15:48:11 ok thinking out loud 15:48:46 I favor docs in the repo that the docs explain 15:49:00 I would like to found docs in a centralized location 15:49:02 THIS instance... as I read it .md file, is not necessarily explaining the bot, it's explaining what to do 15:49:10 s/found/find 15:50:07 also if "you" are the bot and want users help, doc.ansible.com is the location I'd like them to point to. 15:50:42 I'm -1 to having it in docs.ansible.com, because I worry that people will point to `/latest/` which will get out of date 15:50:49 resmo: docs.ansible.com would definitely have a section on how to find collections, where to open issues/PRs on collections etc. Not a direct repeat of this doc but would need that 15:51:02 resmo: yes, that makes sense; I think the reason I'm leaning the other direction is that this content will be (I hope?) temporary - this is about making it through the collections transition 15:51:48 once people are used to the new world order, we should see fewer and fewer "open this issue/PR in the collection repo" comments, and eventually that should stop 15:51:56 or am I being overly optimistic? 15:52:39 I think with the module docs showing up on docs.ansible.com, we may have an ongoing need to educate how to open an issue on the correct collection 15:53:01 but that's different from 'my issue/pr was closed what do I do now'. which is what the bot docs talk about 15:53:05 I started a draft for that use case: https://github.com/ansible/ansible/pull/70488/files 15:53:42 the `Bugs in collections` section 15:54:41 it isn't final, but it's more focused on the future, rather than on the transition 15:55:23 gundalow: I see your point, I think there should be a centralized location for dev docs which is independent from ansible releases: dev-docs.ansible.com 15:56:01 gundalow: to your point, IF we moved the docs to docs.ansible.com, the link in the bot could still be /devel/ 15:56:53 resmo: interesting idea, we are looking at a major overhaul of the documentation in future, and that could be a way forward 15:56:54 resmo: to your point - yes, some future point we want to reorg the docs so there is a clear developer section. That said, so long as /latest/ is open for PRs, I think we'll still need a /latest/ dev guide 15:57:22 samccann: agreed 15:58:17 samccann: yup, I think linking to `/devel` would be OK 15:58:40 longer term splitting the docs up is cool. Though not going to start that discussion today 15:58:56 nope, we have enough on our plates right now 15:59:28 I'm hoping to start that discussion after 2.10 is out the door 15:59:29 so does that change your vote gundalow? Right now we are 2 in favor of keeping docs in the md file, one against, ...and you :-) 15:59:41 (and adbadger1999 seeing both sides of the coin on this one) 15:59:46 lol at `...and you` 16:00:30 I guess my requirements are 16:00:30 1) Link needs to be valid for a couple of years 16:00:30 2) Google needs to direct people to the right place 16:02:03 a markdown file in the bot repo should last as long as the bot is in operation, so I think we're meeting requirement 1 16:02:24 as I mentioned before, not a hill I'm willing to die on 16:02:30 oh, me neither 16:02:59 gundalow: what google search would you expect to hit this page? 16:03:03 I'm fine either way. 16:03:20 I see pros to either decision and neither outweigh the other. 16:03:56 fwiw - google search only links to the top of a page. So if we bring this to docs.ansible.com, it has to be a separate .rst file, not a new section on the existing page that talks about opening up issues and prs 16:06:27 if we bring it to devel docs, it stays there forever, correct? 16:06:41 if we leave it in the bot, it also stays there forever, but isn't in the main docs forever 16:07:55 if we bring it into docs.ansible.com, it becomes much harder to get rid of, yes 16:07:59 ok we're 2 hrs into the docathon. I'm not sure we will get a clear decision on this one. So maybe acozine and I look at the existing issues page on docs.ansible.com, and review the .md file and just make a decision 16:08:44 gundalow: is this the last decision we need on the docs side before setting the bot to work on the backlog? 16:09:01 at least on some carefully chosen portion of the backlog? 16:09:12 acozine: once we are happy with the docs, then open it up to a small subset, 16:09:14 Thanks 16:12:02 okay, so we have 2 items on our to-do list 16:12:24 1. update https://github.com/ansible/ansibullbot/blob/master/templates/collection_migration.j2 to create a link to Galaxy or the new repo 16:13:02 2. make a final decision on the location for the content from https://github.com/ansible/ansibullbot/blob/master/docs/collection_migration.md 16:13:39 1 needs a coder 16:13:46 yeah 16:16:16 gundalow: - how do we get the code changed? do we open an issue with the request? Do we know someone who could quickly just open the PR? 16:17:22 I vote we open an issue on the bot repo. 16:18:56 https://github.com/ansible/ansibullbot/issues/1391 16:19:08 ok let's do that 16:19:36 heh ok you did 16:20:08 it let me close a few tabs in my browser 16:20:27 I need to break for lunch in a bit. Where do we want to go next? keep going here, or come back tomorrow morning and continue the docathon ? 16:20:59 how about we list some easyfix issues here? 16:21:31 folks can pick them up, or post PRs . . . 16:22:14 yup, issue is good 16:22:48 #topic easyfix issues/topics 16:23:25 1. Updating docs to have FQCN for module mentions 16:24:21 ^^^ find rst pages that mention specific modules, update to use Fully Qualified Collection Names (namespace.collection.module) 16:24:54 #info need folks to update the docs to use FQCN for any module mentions in rst pages - use Fully Qualified Collection Names (namespace.collection.module) 16:25:59 2. Updating module docs in collections to use FQCN for M(...) links and Seealso entries 16:26:08 this can be manual, for small collections 16:26:44 or if anyone wants to modify https://github.com/ansible-network/collection_prep for general collection use, that would be awesome 16:26:49 #info update module docs within collectoins to use FQCN for M() and :seealso: entries. Can do this manually 16:27:05 #info or modify https://github.com/ansible-network/collection_prep for general collection use, that would be awesome 16:28:01 3. we have a few issues marked `easyfix`: https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+label%3Adocs+label%3Aeasyfix 16:28:07 (docs issues, that is) 16:31:29 #info see https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+label%3Adocs+label%3Aeasyfix for easy fix docs issues 16:32:03 * gundalow -> food 16:34:04 heh 16:36:01 about to go do the same 16:37:44 I will have my lunch now as well, to keep us all on a similar schedule 16:38:35 (and by "us all" there I meant "folks who have spoken up in chat in the last 30 minutes") 16:39:04 if you're lurking, feel free to grab an issue from the #info links above 16:39:30 or post an idea or comment for the hackathon 16:43:28 * acozine cues up some background music for IRC 18:20:01 * acozine is back 18:20:12 I think the meeting is technically still happening 18:20:33 is anyone around to hack on docs or on Ansible more generally? 18:20:45