16:01:34 <acozine> #startmeeting Docs Working Group aka DaWGs
16:01:34 <zodbot> Meeting started Tue Jan 12 16:01:34 2021 UTC.
16:01:34 <zodbot> This meeting is logged and archived in a public location.
16:01:34 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:01:34 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:34 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
16:01:38 <acozine> #topic opening chatter
16:01:42 <acozine> who's around today?
16:01:45 <samccann> o/
16:01:51 <gwmngilfen> o/
16:01:54 <felixfontein> o/
16:02:01 <acozine> #chair samccann gwmngilfen felixfontein
16:02:01 <zodbot> Current chairs: acozine felixfontein gwmngilfen samccann
16:02:10 <acozine> welcome! good morning/afternoon/evening!
16:02:42 <acozine> felixfontein: do you have tons of snow now? I saw the pictures of people dog-sledding in downtown Madrid, not sure if you got the same storm . . .
16:02:47 * dericcrago waves
16:02:56 <acozine> #chair dericcrago
16:02:56 <zodbot> Current chairs: acozine dericcrago felixfontein gwmngilfen samccann
16:03:02 <acozine> welcome dericcrago!
16:03:27 <felixfontein> acozine: I think in Spain they have a lot more than us :) today it started snowing again though, so let's see ;) but not that much
16:03:47 <felixfontein> it's maybe 2-3 centimeters right now
16:03:56 <felixfontein> but it won't stop until midnight, so I'll find out tomorrow morning when shoveling :)
16:04:13 <acozine> so basically you should send all your snowplows south to help out in Spain?
16:04:15 <bcoca> it snowed in madrid, that is very rare (jsut south of mountain range that normally eats up all the snow)
16:04:24 <acozine> hi bcoca
16:04:26 <acozine> #chair bcoca
16:04:26 <zodbot> Current chairs: acozine bcoca dericcrago felixfontein gwmngilfen samccann
16:04:28 * bcoca waves
16:05:41 <acozine> dmsimard: gundalow alongchamps andersson007_ baptistemm briantist cyberpear JonTheNiceGuy madonius tadeboro tremble you folks talking docs today?
16:05:49 * gundalow waves
16:05:54 <acozine> #chair gundalow
16:05:54 <zodbot> Current chairs: acozine bcoca dericcrago felixfontein gundalow gwmngilfen samccann
16:06:28 <acozine> for anyone who is watching this, and thinking, "my name isn't on that list" . . . please join in!
16:06:52 <acozine> we ping people who have recently participated, or recently opened PRs that we remember, or in some other way shown interest
16:06:59 <acozine> but all are welcome and encouraged to participate
16:07:31 <acozine> today's agenda begins with: https://github.com/ansible/community/issues/579#issuecomment-754770099
16:08:54 <acozine> I think we'll go a bit out of order today, and start with filter/test plugin docs
16:09:02 <acozine> #topic filter/test plugin docs
16:09:13 <acozine> bcoca: can you give us an update?
16:10:11 <alongchamps> I am here this morning
16:10:13 <acozine> background: we are working to extend the documentation infrastructure so we publish docs for all plugins, not just module plugins, from `DOCUMENTATION` sections in the plugin code
16:10:19 <acozine> alongchamps: awesome, welcome!
16:10:22 <acozine> #chair alongchamps
16:10:22 <zodbot> Current chairs: acozine alongchamps bcoca dericcrago felixfontein gundalow gwmngilfen samccann
16:10:24 <alongchamps> o/
16:11:26 <acozine> hm, bcoca has dropped out of range, I guess
16:12:08 <acozine> anyone else have insights/ideas/information on this topic?
16:12:57 <acozine> well, that's too bad
16:13:07 <acozine> okay, moving on . . .
16:13:25 <acozine> #topic role argspec update
16:13:48 <acozine> samccann: I think you heard the latest on this effort
16:13:59 <samccann> Shrews gave a brief update on another channel that I'll repeat here
16:14:24 <acozine> background: we are working to define the argument spec for a role, so we can test and document roles more consistently
16:14:32 <samccann> #info decided to place the argspec in `meta/main.yml` under the `argument_specs` entry.  that was to satisfy a request from felixfontein for future docs reasons.
16:14:42 <samccann> #info we have no doc specific requirements spec'd for it at this time, but i would expect that to be filled out after the initial PoC phase.
16:15:05 <Shrews> If I could, I'd like to lay out what to expect from the role arg spec feature in 2.11. I fear doc expectations are more than what will be delivered.
16:15:49 <samccann> sure any details you can add are welcome here
16:16:01 <Shrews> in 2.11 you can expect: 1) validates role args at task execution time from spec in meta/main.yml,   2) ansible-doc support to output role entrypoints and descriptions.
16:16:32 <Shrews> That's it. We've tried to design with flexibility for future doc requirements in mind, but there will be no specific doc requirements.
16:16:39 <acozine> it will definitely take time to produce correct, complete, and consistent documentation for roles (or even to define what good role documentation looks like)
16:16:48 <acozine> this is a good first step
16:17:06 <felixfontein> will there be some kind of validation for role argument specs?
16:17:10 <acozine> Shrews: is there a current PR or issue folks can look at or follow?
16:18:17 <Shrews> felixfontein: the role arg spec format will be a subset of module arg spec. they will, in fact, share the same code.
16:19:03 <samccann> #info 2.11 you can expect: 1) validates role args at task execution time from spec in meta/main.yml,   2) ansible-doc support to output role entrypoints and descriptions.
16:19:05 <felixfontein> Shrews: I just noticed my question was a bit confusing, I meant sanity-check validation :)
16:19:13 <Shrews> acozine: the ansible-doc changes have already merged. there is still much to do with the actual validation feature
16:19:20 <Shrews> felixfontein: none planned
16:19:26 <samccann> #info the role arg spec format will be a subset of module arg spec. they will, in fact, share the same code.
16:20:26 <acozine> Shrews: sounds good, thanks for the update
16:22:46 <acozine> it sounds to me like validation needs to be finished before we can do much with role documentation
16:22:56 <acozine> what do folks think?
16:23:07 <felixfontein> yes, probably, otherwise it will be a quick descent into chaos ;)
16:23:12 <acozine> heh
16:23:20 <samccann> heh
16:23:20 <Shrews> i think that was the point i was hoping to express  :)
16:23:33 <acozine> I propose putting a note on my calendar to bring this topic up again in a few months
16:23:42 <acozine> maybe in May? after 2.11 is released?
16:23:54 <Shrews> 2.12 would be a good target for that, i think
16:23:54 <acozine> and dropping it from the DaWGs agenda until then
16:24:03 <tadeboro> I do not mind a bit of chaos if I can get rid of manually maintaining rst files with role variables.
16:24:17 <acozine> hi tadeboro
16:24:19 <acozine> #chair tadeboro
16:24:19 <zodbot> Current chairs: acozine alongchamps bcoca dericcrago felixfontein gundalow gwmngilfen samccann tadeboro
16:24:50 <felixfontein> antsibull-docs will do some basic validation, though people will probably not see it in time. but I guess that's something where running sanity tests from devel will be great for :)
16:24:58 <acozine> tadeboro: it's possible we would have chaos and still not be able to get rid of manually maintaining rst files with role variables
16:25:25 <tadeboro> SO I guess I'll dig a bit into it and see if our doc renderer produces anything usefull. Once I read over test cases that is, since they seem to be the only reliabe documentation for now ;)
16:26:11 <acozine> tadeboro: that sounds great - if you see ways we can make progress, definitely put those on the agenda!
16:26:25 <tadeboro> And maintaining rst files is maybe a bit too strong of a wording since for the last year or so, all we did is update supported distros ;)
16:26:41 <acozine> that sounds annoying, but manageable
16:27:16 <samccann> tadeboro: and if your reading of the test cases gives you documentation ideas (how to document the feature so to speak) - please do pop that in a WIP PR so we have something to work with ;-)
16:27:34 <acozine> #agreed tadeboro to investigate ways to move forward with role docs
16:27:54 <acozine> hm, that's probably not the right command
16:28:07 <acozine> #undo
16:28:07 <zodbot> Removing item from minutes: AGREED by acozine at 16:27:34 : tadeboro to investigate ways to move forward with role docs
16:28:59 <acozine> #action tadeboro to investigate ways to move forward with role docs as we wait for role argspec validation
16:29:33 <acozine> #info removing the "update on role argspec" from the agenda for the next few months, will add it back as a regular item after 2.11 release
16:30:17 <acozine> we're at half-way through the hour
16:30:46 <acozine> #topic template for collection `/docs/` folder
16:31:07 <abadger1999> Good morning
16:31:15 <acozine> morning abadger1999!
16:31:18 <acozine> #chair abadger1999
16:31:18 <zodbot> Current chairs: abadger1999 acozine alongchamps bcoca dericcrago felixfontein gundalow gwmngilfen samccann tadeboro
16:31:45 <acozine> samccann: and abadger1999 and I were talking yesterday about the docsite split
16:32:16 <acozine> and we'd like to see content like the Scenario Guides moved to collections
16:32:39 <felixfontein> :+1:
16:32:44 <acozine> this means we need some kind of template, some guidelines, for using that `/docs/` folder
16:33:03 <acozine> we don't have to enforce it
16:33:21 <acozine> I mean, we don't need to say "you can only put these files in this order in this format here"
16:33:44 <acozine> but we can say "if you want this documentation published on docs.ansible.com, you can only put these files in this order in this format here"
16:34:02 <felixfontein> I guess the big question is what happens to these files. are they included in the docsite? if yes, which requirements do they have to satisfy? (w.r.t. label names)
16:34:30 <acozine> yep, good questions
16:35:00 <samccann> yeah I want to say felixfontein maybe was the one to point out a bit back that we'd have to define some way to have unique labels for crossreferences. Though they may be a 'added' by the pipeline somehow?
16:35:12 <abadger1999> Uh..... Note that if the /docs/ folder gets used for other things, it potentially could cause some problems.
16:35:17 * samccann loves to sprinkle magic docs pixiedust into antsibull
16:35:49 <felixfontein> I wonder whether there is a simple way to programmatically extract a list of labels from a .rst file. with that, it would be possible to have both a validator, and a sanity check to make sure antisbull-docs ignores files that don't validate
16:35:54 <acozine> abadger1999: can we define a single subfolder that would be the only one we care about for publishing to docs.ansible.com?
16:35:56 <felixfontein> (and potentially screw up the docsite)
16:35:58 <samccann> yeah my thinking is we would take over 'something'.  If it's not /docs, then it's /docs/docsite or some other subfolder that says you HAVE to do things our way here
16:36:33 <samccann> labels - I was thinking the pipeline just prepends the collection name to the label. That I think would guarantee unique across all collection /docs folders
16:37:09 <abadger1999> acozine: Yeah.  As long as that folder is not used by any collection for something unrelated to the docsite build that should be fine.
16:37:15 <samccann> acozine - not sure how much of this you want info'd vs its just brainstorming ideas?
16:37:22 <acozine> hmmm
16:37:48 <acozine> maybe we can turn the discussion into an issue (on ansible/ansible, or on ansible-collections/general) after the meeting?
16:38:12 <acozine> instead of info-ing everything?
16:38:19 <samccann> k sounds like a plan, stan
16:38:22 <felixfontein> samccann: it's probably easier to avoid that automatically label rewriting, because that requires us to somehow rewrite the RST file - sounds a lot more complicated than validating it
16:38:44 <abadger1999> #info directory: we're going to propose allocating a specific subdirectory in the collection for building docsite content from.  Nothing unrelated to the docsite should be placed there.
16:39:03 <acozine> and add a sanity test to enforce ^^^
16:39:15 <abadger1999> felixfontein: +1
16:39:17 <samccann> #info need 'some way' to make labels unique across all the collections
16:39:39 <acozine> can we also validate that all labels in the special directory begin with the collection name?
16:40:13 <felixfontein> samccann: I guess the easiest would be to make sure that all labels start with a prefix that's composed of the collection name. for that we need to be able to extract a list of labels from a .rst file. maybe it's possible with rstcheck, or rstcheck's sources
16:40:26 <felixfontein> acozine: +1
16:40:34 <abadger1999> Yeah, if we define that.  And making sure they're uniq probably means including the collection name somehow.
16:40:50 <acozine> and we're requiring rst
16:41:07 <acozine> I mean, all files in the special directory must be in .rst format
16:41:17 <abadger1999> Something like `.. _anscoll_community_crypto::`
16:41:17 <felixfontein> resp. everything that's not .rst is ignored
16:41:27 <acozine> heh
16:41:53 <acozine> sounds good
16:41:59 <samccann> well we could need images, not just .rst
16:42:07 <abadger1999> Well, `.. _anscoll_community_crypto_LABEL::` (_anscoll_community_crypto_ is the part that uniquifies the label.
16:42:34 <acozine> abadger1999: yeah
16:42:52 <samccann> what is anscoll in that? vs just community_crypto_LABEL ?
16:43:24 <acozine> I wonder if there's an rst shortcut or config option where you can say "prepend_to_all_labels: foo"
16:44:11 <tadeboro> Labels can be tricky, but I have a feeling that things like :doc:`my text </path/to/file>` will be even trickier.
16:44:22 <abadger1999> samccann: We need something in addition to the collection namespace and name to make sure it's unique.
16:44:34 <tadeboro> Unless we limit things down to more basic subset of what Sphinx supports.
16:44:47 <acozine> tadeboro: yeah, and it would be good to allow links from other areas of the docs TO those collections-based docs too
16:45:10 <felixfontein> we definitely need an exclusion list which we can use to stop including docs/.../ from collections that screw up
16:45:34 <abadger1999> samccann: Otherwise the docsite might have a label like community_general    for General questions about the ansible community and that could conflict with a label inside of the collection docs.
16:45:35 <samccann> #info an example of a potential label would be  `.. _anscoll_community_crypto_LABEL::` (_anscoll_community_crypto_ is the part that uniquifies the label.
16:45:43 <acozine> felixfontein: or an inclusion list, perhaps?
16:45:48 <samccann> yeah good point abadger1999
16:46:24 <felixfontein> acozine: that would also be ok, though maybe more work to keep it up-to-date
16:46:33 <felixfontein> assuming that most collections don't screw it up:)
16:46:43 <tadeboro> Bold assumption ;)
16:46:44 <acozine> so we only publish from the `/docs/` folder from collections that meet requirements (pass the sanity checks, etc.)
16:47:05 <samccann> my nickel - in the perfect world, all sphinx 'stuff' would work so long as it complies with our Ansible style guide.  That's probably wishful thinking, but still
16:47:10 <abadger1999> acozine: If there is something that can prepend to all labels, it would have to work per-page rather than over the whole document.  I know there's something for rst roles that work that way but I don't think there is something for refs/labels.
16:47:48 <acozine> that's too bad
16:47:55 <samccann> abadger1999 - i'm more in favor of a sanity test now that validates all labels in a collection have the format suggested above (or some variant)
16:48:11 <samccann> as in the docs author puts in the labels, if they are wrong, we flag it via a validation CI test
16:48:18 <abadger1999> #info need a way to exclude collections whose docs are bad (for instance, contain conflicting labels)
16:48:30 <abadger1999> samccann: <nod>
16:49:08 <abadger1999> #undo
16:49:08 <zodbot> Removing item from minutes: INFO by abadger1999 at 16:48:18 : need a way to exclude collections whose docs are bad (for instance, contain conflicting labels)
16:49:29 <abadger1999> #info need a way to exclude collections whose docs are bad (for instance, contain conflicting labels) or include the collections that are known good.
16:49:51 <tadeboro> What about making a separate site for each collection and linking them using intersphinx?
16:50:24 <tadeboro> We could automatically add Sphinx config and other magic so that the collection authors only need to provide the text.
16:50:31 <samccann> that's... a lot of sites
16:50:58 <felixfontein> not sure how that will work with the sidebar / table of contents
16:51:04 <samccann> I think in the 'perfect future world' these docs are visible directly in Galaxy-ng or something.
16:51:17 <abadger1999> I think that's a more intrusive change but we would get things like non-conflicting labels for free.  It puts the burden on the task creating the docsite rather than each collection doc author.
16:51:24 <abadger1999> So I somewhat like it.
16:51:39 <bcoca> ^ on docs, nothing usable yet
16:51:50 <acozine> tadeboro: so instead of https://docs.ansible.com/ansible/latest/collections/community/postgresql/index.html#plugins-in-community-postgresql we would have . . . what?
16:52:07 <abadger1999> That would open up a question about how we organize all of those, though.  And do we try to make the separate docs transparent to the users or very visible?
16:52:31 <tadeboro> I would not change the urls, just the implementationdetails of how things get there.
16:53:07 <acozine> ah, so each collection would need its own sphinx config file?
16:53:23 <tadeboro> For example, we have all of our docs at https://docs.steampunk.si: https://docs.steampunk.si/unit/ for NGINX Unit, https://docs.steampunk.si/aws/ for AWS, ...
16:53:47 <abadger1999> samccann: note that the galaxy team currently is planning on each collection being independent of every other one.  So there is a lack of crosslinking.  Perhaps even a lack of crosslinking to the ansible docs.
16:54:03 <tadeboro> What we do not have is a toplevel index file that would link to all those, but mainly because I am lazy ;)
16:54:25 <tadeboro> AH does render *.md files from the docs folder. And I would assume galaxy_ng does the same.
16:54:53 <felixfontein> is there any public information on what the galaxy team is planning?
16:54:57 <acozine> tadeboro: what defines them as "separate sites"?
16:55:16 <acozine> felixfontein: I do not know of any, but I have not looked
16:55:28 <acozine> we could definitely gather more information on that
16:55:38 <acozine> s/that/what the galaxy team is planning
16:55:39 <abadger1999> felixfontein: I don't know.  i've gleaned all of my information from talking to them, one off, on slack.
16:56:08 <samccann> sounds like we need to start a drive for a... /docs directory 'spec' :-)
16:56:20 <tadeboro> Each of them is generated from its own Sphinx site. SO they have nothing in common (besides the fact that I copied over the general structure, theme, ...).
16:56:57 <acozine> tadeboro: so each one has its own sphinx config, theme, and TOC
16:57:30 <felixfontein> tadeboro: so there's no global navigation tree, ...?
16:57:59 <tadeboro> acozine: Yes. But as I said, most of the non-text stuff is just copy-paste.
16:58:30 <abadger1999> samccann: +1 for a specification :-)
16:58:37 <tadeboro> acozine: And the global navigation is missing because we did not need it yet. ANd because I am lazy ;)
16:58:53 <acozine> tadeboro: understood, and if we had a "drop-in Ansible theme" as we've discussed in the past, it might be even less trouble than copy/paste
16:59:49 <tadeboro> That is what I was proposing: to auto-add all the theme and config stuff. docs folder can then contain just the content.
17:00:10 <samccann> channeling my inner cybet(te) - we are at the 1 hr mark
17:00:17 <acozine> heh, yeah
17:00:19 <felixfontein> :)
17:00:28 <samccann> it's so helpful I find!  :-)
17:00:29 <acozine> okay, we've got some good ideas, and some next steps
17:00:31 <abadger1999> Implementation note: we'd need to generate the docsite conf.py at build time so we can list all of the separate documents in the intersphinx configuration.
17:01:02 <samccann> acozine - did you want to agree or action those next steps for the meeting minutes?
17:01:10 <acozine> #action acozine to summarize today's conversation in a proposal or issue
17:01:17 <abadger1999> We probably need to specify that each of the sub-sites has an index.rst at the toplevel which they intend as the entrypoint to the docs.
17:01:48 <felixfontein> so what exactly will be in the sib-site? also all the plugin/module docs?
17:01:49 <samccann> yeah we may need that index.rst no matter what - to put a logical order if they have more than one file
17:02:37 <felixfontein> also this would complicate antsibull-docs, if it should stay usable for other docsites which don't follow this scheme
17:02:42 <acozine> felixfontein: I think if we go the "separate sites" route, we'll need some kind of global nav to link them together, and yes, all the documentation from one collection would be published in that collection's site
17:02:55 <abadger1999> One thing to add to the proposal is how we want the autogenerated module docs to fit into this structure... is it separate?  Does the collection's sphinx config determine how it's linked in (if at all)?
17:03:21 <acozine> it sounds like this is a proposal, not an issue, and it should include Pros/Cons sections for each idea
17:03:31 <tadeboro> What we do is have a complete Sphinx site inside docs, and the module documentation gets extracted into subfolder before rendering.
17:04:08 <acozine> I'll post a link to the proposal here later today or possibly tomorrow
17:04:19 <tadeboro> https://github.com/sensu/sensu-go-ansible/blob/master/docs/Makefile.custom is what we do to render things.
17:04:20 <samccann> acozine: yeah we need space/place to debate so a proposal on the github discussions over ..er.. on ansible-collections (and put in the bullhorn) sounds like a plan
17:04:27 <acozine> then ask you all to add links, ideas, objections, etc.
17:04:36 <acozine> tadeboro: thanks!
17:04:42 <acozine> okay, we're five minutes past
17:05:02 <acozine> and we haven't touched on the survey or done an open floor
17:05:12 <acozine> I propose five minutes for each
17:05:22 <abadger1999> tadeboro: <nod>  Yeah.  If we follow that model exactly, though, then it's possible that a collection could decide to omit the autogenerated module docs (for instance).  So I'm not sure if we want to place some policy limitations on that or do it differently on a technical level.
17:05:32 <acozine> #topic docs user survey results
17:05:55 <acozine> gwmngilfen: I'll start with my "Top Takeaways" from teh results you sent
17:06:01 <acozine> then you can take it from there?
17:06:29 <acozine> of the >800 responses
17:06:32 <gwmngilfen> sure
17:06:58 <acozine> 27% said they were "very happy" and another 33% said they were "slightly happy" with the Ansible docs
17:07:10 <acozine> only 9.6% said they were "very unhappy"
17:07:24 <acozine> that makes me happy
17:07:25 <samccann> should we info these?
17:07:31 <acozine> samccann: sure
17:07:33 <samccann> or is this just preliminary stuff
17:07:34 <samccann> k
17:07:37 <felixfontein> do we know why they are "very unhappy"?
17:07:42 <gwmngilfen> i can render that doc to html and make it public, if you wish ;)
17:07:49 <samccann> #info 27% said they were "very happy" and another 33% said they were "slightly happy" with the Ansible docs
17:07:50 <samccann> 12:07 PM only 9.6% said they were "very unhappy"
17:08:05 <samccann> #info only 9.6% said they were "very unhappy"
17:08:15 <samccann> (in case that last part didn't work)
17:08:26 <gwmngilfen> samccann: so far I have only copied the raw question results out of survey monkey. there is far more we can do, but we'll get to that in a moment :)
17:08:29 <acozine> felixfontein: not directly, though we can look at the other answers from those who said they were very unhappy, to see if those give us any clues
17:08:44 <acozine> gwmngilfen: what would you like to highlight?
17:08:48 <samccann> +1 for making the results public once you have it all worked out etc
17:09:00 <gwmngilfen> give me a moment
17:10:02 <gwmngilfen> https://stats.eng.ansible.com/apps/docs/docs-survey.html
17:10:53 <gwmngilfen> these are the raw auto-generated plots from surveymonkey. As such, they don't give you a lot of insight into sections of the data.
17:11:25 <samccann> #info raw data from the survey (more insights to come later ) - https://stats.eng.ansible.com/apps/docs/docs-survey.html
17:11:58 <gwmngilfen> the next step is to think about what questions you'd like to answer that draw on multiple questions, such as "what are the ratings of the docs between the different types of user" or "how does the experience of the user affect other questions" etc
17:12:52 <gwmngilfen> i'm happy to meet up with acozine for some drilling down into this, but I'm sure input from everyone on what questions might be in scope :)
17:13:08 <acozine> personally I'm interested in whether there's a difference in average happiness between sysadmins and network admins
17:13:14 <gwmngilfen> *input is welcome ...
17:13:38 <acozine> and yes, everyone can participate in playing with these results
17:14:01 <acozine> ideas/questions/comments welcome!
17:14:04 <gwmngilfen> yep, rating vs role is absolutely on my radar.
17:14:08 <acozine> also, we hope to do this again in future
17:14:20 <acozine> so ways to improve the survey would also be good
17:14:21 <gwmngilfen> also, there are ~1200 text comments, so I have to figure out some analysis for that
17:14:41 <acozine> I know we need to change the question about "do you use Ansible at work or for personal projects" so there's a "both" option
17:14:55 <acozine> we can make other tweaks
17:15:15 <gwmngilfen> the discussion I had with JP on twitter could probably be worked into the last question
17:15:39 <acozine> you'll have to fill me in on the conversation, I am not in twitter
17:15:44 <acozine> s/in/on
17:16:02 <acozine> we'll schedule a longer update next week or the week after
17:16:12 <acozine> meanwhile, post questions here any time, folks!
17:16:15 <gwmngilfen> ugh, looks like JP auto-deletes tweets
17:16:24 <acozine> #topic open floor
17:16:43 <felixfontein> I have a question about the Ansible 3.0.0 porting guide
17:16:44 <gwmngilfen> anyway, he misunderstood the point of the last question - asking a very RH centric question made him upset
17:16:48 <felixfontein> https://github.com/ansible-community/antsibull/pull/231#issuecomment-757371797
17:16:59 <gwmngilfen> until I pointed out that it exists to ensure that the survey results are not dominated by RHers
17:17:23 <felixfontein> I created a mock of how the changelog and porting guide for 3.0.0 could look like: https://gist.github.com/felixfontein/f470ec58f0706fdde84228dbc99b2e50 (created by PR https://github.com/ansible-community/antsibull/pull/231)
17:18:24 <felixfontein> the changelog part is clear I think, but about the porting guide (https://gist.github.com/felixfontein/f470ec58f0706fdde84228dbc99b2e50#file-porting_guide_3-rst): I guess it should not contain the ansible-base 2.10 porting guide, since it is not needed to upgrade from Ansible 2.10 to Ansible 3
17:18:28 <acozine> felixfontein: that looks nice
17:18:48 <felixfontein> if that sounds good, the question is, what to do instead :)
17:19:12 <acozine> do we link to the "list of all included collections" anywhere?
17:19:59 <acozine> how easy is it for a user to find "Contents of this package: base/core version, included collections with versions"?
17:20:33 <samccann> hmm thinking aloud about not having ansible-base 2.10 - if there are changes in base in say 2.10.33 and that is part of Ansible 3.x, how would a user know about those changes if we don't continue to include base porting guide in Ansible porting guides?
17:21:15 <felixfontein> acozine: there's the `Ansible-base` and the `Included collections` list in the changelog entry for 3.0.0: https://gist.github.com/felixfontein/f470ec58f0706fdde84228dbc99b2e50#ansible-base
17:21:32 <acozine> felixfontein: ah, perfect, thanks
17:21:54 <felixfontein> samccann: ansible-base 2.10.x for x > 0 is not supposed to have anything that should be mentioned in the porting guide
17:22:23 <acozine> aren't the changes listed under `Playbook` and `Command Line` changes to ansible-base?
17:22:24 <abadger1999> In the past, they have.
17:22:44 <abadger1999> felixfontein: ^
17:23:05 <felixfontein> also it should be containde in the ansible-base changelog. if it uses the correct sections, we could auto-include it in the generated porting guide (or maybe we already do)
17:23:29 <abadger1999> I think reasons have been Minor breaking changes due to security fixes and changes that occurred in ansible-2.10.0 but weren't documented in the porting guide until later.
17:23:34 <felixfontein> abadger1999: there's no way to automatically extract that from the porting guide document though, you'd need to look at the diff and decide how to format the diff
17:23:44 <abadger1999> Yeah
17:24:26 <samccann> felixfontein - what is the benefit of removing ansible-base porting guide from 3.x?
17:25:21 <felixfontein> abadger1999: maybe inserting the correct sections of the ansible-base changelog into the auto-generated porting guide would be fine? if the correct sections (major_change, breaking_change, deprecated_features, ...) are used in the changelog, that is...
17:25:46 <felixfontein> samccann: mainly because it feels wrong, because it documents changes since Ansible 2.9, but the Ansible 3 porting guide should document changes since Ansible 2.10
17:26:27 <abadger1999> samccann: In the normal case, those changes occurred when migrating from ansible-2.9 to ansible-2.10 (as that was when the ansible-base version was made).  So a user upgrading from ansible-2.10 to ansible-3.0 would be reading information that they'd already dealt with in the previous upgrade.
17:26:34 <acozine> so some, but not all, changes are relevant to a user upgrading from Ansible 2.10 to Ansible 3.0
17:26:59 <abadger1999> Yes... and in all likelihood, some is a very small number
17:28:29 <felixfontein> if the ansible-base porting guide would be auto-generated, it would be a lot easier
17:28:44 <samccann> how easy/hard would it be to put in a note to say 'Ansible 3.x.y includes ansible-base 2.10.x  - see the changelog for any important changes
17:29:05 <samccann> as in put that manual note in instead of repeating the 2.10 base porting guide?
17:29:45 <felixfontein> btw, here's a list of changes to the ansible-base 2.10 porting guide: https://github.com/ansible/ansible/commits/devel/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst
17:31:34 <samccann> yeah that emphasizes my worries - I think two of those entries were for CVEs. so 3.x porting guide wouldn't show that detail
17:32:15 <felixfontein> the stable-2.10 changelog once had an entry which would have resulted in an automatic porting guide entry: https://github.com/ansible/ansible/blob/stable-2.10/changelogs/CHANGELOG-v2.10.rst#breaking-changes-porting-guide
17:32:55 <felixfontein> and in fact it was also integrated in the automatic Ansible 2.10 porting guide: https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_2.10.html#porting-guide-for-v2-10-2
17:33:56 <acozine> we can propose automating the base/core porting guide based on changelog entries
17:34:05 <felixfontein> the one CVE had its changelog fragment labelled as security_fix, and had no breaking_changes entry (https://github.com/ansible/ansible/pull/71537/files), so it would not how up in the porting guide
17:34:47 <acozine> I don't know if that would be controversial or not
17:35:21 <acozine> felixfontein: how soon do we need a definitive answer?
17:35:23 <samccann> ah thanks felixfontein - didn't know CVEs are only in changelog (unless breaking)
17:36:22 <felixfontein> samccann: CVE fixes are not necessarily breaking changes, so they don't automatically belong in the porting guide IMO
17:36:57 <acozine> true, they are often more "reasons to upgrade" than "reasons this upgrade will break things"
17:36:59 <felixfontein> samccann: the best way would to use both sections in a changelog fragment if applicable. in that case the same fix shows up multiple times in the same changelog, but these would be multiple aspects
17:37:06 <felixfontein> like different roles ;)
17:37:15 <abadger1999> felixfontein: +1 for both sections
17:37:30 <samccann> my off the cuff response is that if CVEs show up and are findable in Ansible 3.x 'where users expect them to be" I'm okay w/ dropping 2.10 porting guide from 3.x
17:37:54 <felixfontein> CVEs usually always show up in the changelog (if they have a changelog fragment, that is :) )
17:38:01 <samccann> heh
17:38:09 <acozine> +1 for "usually always"
17:38:58 <felixfontein> :)
17:39:26 <felixfontein> collections that don't have changelogs that are incorporated into the auto-generated changelog could have security fixes that nobody notices
17:40:05 <samccann> time check - 40 min over the 1 hr meeting :-)
17:40:39 <felixfontein> sounds like the community meeting :D
17:40:40 <acozine> sigh
17:40:55 <felixfontein> I'll have to prepare dinner now
17:41:03 <acozine> felixfontein: let's revisit next week unless you need an answer now
17:41:10 <acozine> s/now/sooner
17:41:38 <felixfontein> acozine: sounds good. 3.0.0 is still out, and so is its first beta version, so it's not urgent ;)
17:42:04 <acozine> thanks abadger1999 alongchamps bcoca dericcrago felixfontein gundalow gwmngilfen samccann tadeboro
17:42:18 <acozine> felixfontein: awesome
17:42:24 <acozine> thanks again everyone
17:42:37 <acozine> look for updates in this channel over the next day or two
17:42:40 <acozine> #endmeeting