15:30:07 <gundalow> #startmeeting Ansible Documentation Working Group
15:30:07 <zodbot> Meeting started Tue Nov  6 15:30:07 2018 UTC.
15:30:07 <zodbot> This meeting is logged and archived in a public location.
15:30:07 <zodbot> The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:30:07 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:30:07 <zodbot> The meeting name has been set to 'ansible_documentation_working_group'
15:30:21 <gundalow> #chair acozine samccann
15:30:21 <zodbot> Current chairs: acozine gundalow samccann
15:30:27 * gundalow waves
15:30:30 <gundalow> Who else is around?
15:30:57 * acozine hears crickets
15:31:27 <gundalow> herald85: Hi, you here for Docs meeting?
15:31:50 * felixfontein waves back
15:31:50 * acozine grabbing tea from kitchen, back in a sec
15:32:05 <samccann> here
15:32:17 <felixfontein> (at least half-listening)
15:33:04 * acozine back
15:33:16 <acozine> hi Felix
15:34:21 <acozine> following up on last week's discussion about backports
15:34:30 <gundalow> #topic Backports
15:34:32 <gundalow> #chair felixfontein
15:34:32 <zodbot> Current chairs: acozine felixfontein gundalow samccann
15:34:53 <acozine> samccann and gundalow and I got a bunch of backport PRs done for documentation this week
15:35:05 <acozine> and we discovered how far behind we'd gotten
15:35:59 <acozine> so there are some docs PRs that were merged to `devel` that have not been backported
15:36:18 <acozine> it's a judgment call
15:37:03 <acozine> so if folks here have PRs that they'd like to see backported that have not been done already, please open backports
15:37:27 <gundalow> Can we detect/automate any of this?
15:37:40 <gundalow> ie make our lives easier
15:37:55 <samccann> do we have a guideline? always open backport for at least the 'latest' branch? or always go back at least 2 branches if the PR is applicable?
15:38:51 <acozine> https://docs.ansible.com/ansible/latest/community/development_process.html?highlight=backport#backport-pull-request-process
15:39:37 <samccann> #info use this link to understand the backport process - https://docs.ansible.com/ansible/latest/community/development_process.html?highlight=backport#backport-pull-request-process
15:40:40 <samccann> I haven't noticed an 'existing' way to figure out if a PR was backported. Except that if you mentioned the original PR in the backport PR, this mention will show up in the original PR comment thread
15:40:42 <acozine> gundalow: I don't know if we can automate backporting - it would be nice if we could
15:40:44 * gundalow personally just backports to latest stable for docs fixes, unless it's a major way
15:40:45 <samccann> not alas, ideal
15:41:17 <acozine> samccann: yeah, if you follow the procedure from the docs, I think it updates the original PR
15:41:39 <samccann> can we/should we adopt gundalows backport target? (aka always backport to stable unless it's a major bugfix/clarification etc?
15:41:50 <acozine> +1 from me
15:41:53 <samccann> +1
15:42:22 <felixfontein> if the original PR was squash-merged, git cherry-pick includes the original PR's number in its commit message, so the original PR gets a notification
15:42:27 <gundalow> #action agreed that docs PRs (apart from new features) should be backported into latest stable
15:42:32 <gundalow> #undo
15:42:32 <zodbot> Removing item from minutes: ACTION by gundalow at 15:42:27 : agreed that docs PRs (apart from new features) should be backported into latest stable
15:42:53 <gundalow> #agreed that docs PRs (apart from new features) should be backported into latest stable
15:43:01 <felixfontein> I usually backport to the last two stables (if applicable), I did that for both regular bugfixes / tests / ... and for docs. no idea if that's always a good idea though :)
15:43:34 <felixfontein> for minor docs PRs, the current latest stable should be fine
15:43:56 <samccann> filixfontein: do you usually backport right after you merge a PR?  just curious how people are keeping up with backport backlog
15:44:08 <samccann> felixfontein^^
15:44:44 <felixfontein> I can't merge ;) but as soon as someone merges, I do the PR (otherwise I'll just forget about it)
15:45:13 <acozine> we will certainly accept backports to `stable_2.x` as far back as folks want
15:45:20 <felixfontein> in some cases (when I can't backport because too many other backports are not merged which contain changes this new change is based on) I keep the browser tab with the PR open so I won't forget, and add a note to the PR that I'll backport later
15:45:31 <bcoca> i think that is part of bigger conversation, i wanted to have a 'backport candidate' either label or project
15:46:08 <samccann> +1 on a label
15:46:20 <acozine> I'd been using a GitHub project - PRs went from In Progress to Backport to X.X, then I did a bunch at a time when the column got full
15:46:52 <acozine> but I got behindhand
15:46:55 <felixfontein> it is not always simple to decide (for ansibot) whether the PR can be backported or not (for module docs, it depends on whether the features it affects were in earlier releases). but some automatic labeling (which can be modified by maintainers via ansibot) would be good
15:47:09 <bcoca> label would be manual
15:47:23 <bcoca> or project, since we might want to backport to more than n-1
15:47:33 <bcoca> but i think this is a more general discussion, not just docs
15:47:50 <acozine> for docs, we've got https://github.com/ansible/ansible/projects/27
15:48:30 <bcoca> acozine: i would not make a project for backport 'per type' but 'per version'
15:48:59 <bcoca> also, what does Backpor to 2.7 mean? issues merged into devel but need a backport, or backport issues themselves?
15:49:20 <felixfontein> bcoca: maybe some backport-triage label, which can be (with ansibot) changed to some combination to should-be-backported-to-2.7, should-be-backported-to-2.6, ... labels
15:49:49 <acozine> bcoca: I wrestled with that - the way I used it, I put the PR that needed a backport into the column, then added the PR that backported it there, once all were merged, I stacked them next to each other in the Done column
15:50:03 <acozine> that was just to avoid having fifteen columns
15:50:23 <bcoca> he, fun!
15:51:35 <samccann> if there were labels, could that be use to autopopulate a project?
15:52:04 <sivel> fwiw, there have been discussions, nothing official, that we may be doing too many backports for our own good, by effectively backporting everything.
15:52:10 <sivel> Not super related to docs, but just an FYI
15:53:29 <acozine> sivel: good point - long-term, though, we are trying to drive traffic coming to docs.ansible.com to the `latest` docs, which means all useful changes to docs need to get backported at least that far
15:53:49 <gundalow> #chair sivel bcoca
15:53:49 <zodbot> Current chairs: acozine bcoca felixfontein gundalow samccann sivel
15:53:52 <samccann> we need to define useful in this context
15:53:56 <gundalow> sivel:  That's an interesting point
15:54:18 <samccann> 'bugfixes' are useful.  are 'clarifications' useful/important enough for a backport etc?
15:56:12 <acozine> I like to have the latest improvements available to users right away, without sending them to `devel`
15:56:25 <acozine> but I take your point samccann
15:56:38 <acozine> we don't need to backport everything
15:57:07 <acozine> which is good, since we haven't been . . .
15:57:45 <samccann> so we can try it for a time in docs and see how it goes.  With the dual approach of asking the folks who created the PR to backport to latest...and then going in  maybe 'byweekly' for a batch backport for those that haven't happened yet.
15:57:53 <gundalow> yup, I've only backported things where I've though it's a useful change (and worth my & Release Managers time)
15:58:39 <acozine> samccann: sounds good
15:58:48 <acozine> anything else on backports?
15:59:54 <samccann> #agreed PR creators should be encouraged to backport to stable release when their PR is merged
16:00:20 <samccann> #undo
16:00:20 <zodbot> Removing item from minutes: AGREED by samccann at 15:59:54 : PR creators should be encouraged to backport to stable release when their PR is merged
16:00:33 <acozine> samccann: ??
16:00:39 <samccann> #agreed PR creators should be encouraged to backport to stable release when their PR is merged for PRs that improve/ are useful
16:00:51 <acozine> heh, right
16:00:55 <gundalow> :)
16:00:56 <samccann> ..wanted to capture that distinction
16:01:01 <gundalow> What's next #topic ?
16:01:12 <acozine> #topic PR review
16:01:37 <acozine> we're back up to >90 open docs PRs but I think a bunch are fairly easy to deal with
16:01:55 <acozine> https://github.com/ansible/ansible/pull/48066/files
16:02:05 <gundalow> #topic PR review
16:02:05 <acozine> thoughts on ^^^?
16:02:25 <gundalow> #info add note regarding {host,group}_vars directory lookup semantics #48066
16:03:13 <gundalow> bcoca: you saying that should be When running the ``ansible`` or ``ansible-console``  commands (rather than
16:04:11 <bcoca> --playbook-dir applies to both, not just adhoc
16:04:26 <bcoca> .. i think also ansible-inventory, need to x2 check
16:04:36 <acozine> ah, I needed to refresh
16:04:47 <bcoca> probalby shorter 'other ansible commands aside from ansible-playbook'
16:04:48 <gundalow> acozine: apart from bcoca's comments it seems OK
16:04:59 <gundalow> bcoca: that sounds nice and future proof
16:05:06 <acozine> bcoca: good thinking
16:05:27 <bcoca> mostly being lazy and not wanting to update every time we add a utility ...
16:05:36 <gundalow> lazy is good
16:05:41 <gundalow> (in this context)
16:06:03 <bcoca> ^ don't tell my mother .. years of yelling at me have not worked
16:07:47 <acozine> heh
16:09:01 <acozine> last week we talked about `loop` and `with_x` - I've got an open PR with several comments (thanks sivel: and bcoca:) - I'll address those - any other suggestions?
16:09:16 <acozine> https://github.com/ansible/ansible/pull/47895/files
16:09:53 <acozine> once that one's merged, I think we can either merge or close the other "with_x is obsolete" PRs based on the guidelines in the loop docs
16:13:03 <samccann> i have another PR I could use some help on - https://github.com/ansible/ansible/pull/47507#discussion_r228310194
16:13:45 <samccann> it's stalled because I don't have the facilities/know-how to reproduce the issue, so not sure if the proposed fix is required or not (as seen in the comment thread)
16:14:52 <gundalow> samccann: You can ping rambleraptor erjohnso on GitHub, they maintain the modules
16:15:31 <acozine> samccann: oh, interesting - thanks for catching that `scopes` is described in the shared docs
16:15:36 <gundalow> Also those modules are autogenerated, so rambleraptor erjohnson will need to update their upstream generator
16:15:51 <acozine> so the question is, is `scopes` required for all modules that share that documentation?
16:16:02 <acozine> or is it only required for some modules . . .
16:16:18 <acozine> if it's required for all modules, then we can update the shared doc fragment
16:16:28 <acozine> if it's only required for some, then we have a bigger set of changes to make
16:16:34 * gundalow would make it Google's problem and move on
16:16:40 <gundalow> I can drop them an email
16:17:03 <samccann> also, there's a question on the code itself, as it 'looks' like it should fill in a default if there is not scopes... but according to the PR, that's not happening correctly
16:17:31 <samccann> thanks gundalow.  I'll add them to the comments and see if that can nudge things along
16:18:18 <gundalow> Thanks, I've emailed and asked if they can take a look at the issue
16:18:25 <acozine> what about this one: https://github.com/ansible/ansible/pull/48156/files?
16:18:30 * samccann needs to pay more attention to that support:community label
16:18:47 <acozine> bcoca: I see you said the change in 48156 is incorrect
16:19:04 <acozine> can we close it?
16:19:23 <acozine> I wish I understood why the author thought the change was correct . . .
16:19:47 <acozine> so we could use the PR as an educational opportunity
16:20:21 <gundalow> Something in `plugins/inventory/ini.py `?
16:20:58 <gundalow> https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/inventory/ini.py#L17
16:21:14 <bcoca> i think author misunderstands what 'python literal' means
16:21:49 <bcoca> gundalow: the problem is that does and does not apply at same time
16:22:03 <acozine> bcoca: interesting - so maybe another example would help clarify?
16:22:05 <bcoca> only 'hostvars in k=v' format inline to the host declaration do that, group vars do not
16:22:26 <bcoca> line 33 in file, that is an int
16:22:32 <bcoca> line 37, its a string
16:22:49 <bcoca> FUN!
16:23:03 <sivel> There is actually a bug filed about that, but we do not intend on changing that behavior
16:23:03 <gundalow> #chairs
16:23:07 <gundalow> #chair
16:23:07 <zodbot> Current chairs: acozine bcoca felixfontein gundalow samccann sivel
16:23:10 <bcoca> so in the end both are right/wrong
16:23:35 * gundalow -> afk
16:23:50 <acozine> sivel: do you have a link to the bug handy?
16:24:03 <sivel> no, but I can search
16:24:15 <acozine> thanks
16:24:47 <sivel> https://github.com/ansible/ansible/issues/36544
16:25:56 <acozine> cool, I'll link the PR to the issue and work on clarifying the behavior in the docs
16:26:33 <acozine> we've got 4 minutes left . . . . anybody have anything they want to bring up?
16:26:59 <acozine> dang, I didn't check the agenda . . .
16:27:31 <acozine> heh, and I skipped something I wanted to discuss
16:27:32 <acozine> sigh
16:27:35 <samccann> :)
16:27:49 <acozine> agenda is available at https://github.com/ansible/community/issues/389
16:27:59 <bcoca> https://github.com/ansible/ansible/pull/48169
16:28:56 <acozine> bcoca: thanks! and yes, that is a bit insane
16:29:15 <acozine> for next week, I'd like to look at the "better breadcrumbs" proposal
16:29:26 <acozine> it's linked in the agenda ^^^
16:29:35 <bcoca> also, partially my fault, i added the typing to hostvars, but forgot about group vars
16:29:42 <bcoca> back in 0.6 version?
16:29:47 <acozine> original sin
16:29:53 <bcoca> changing it now just causes too many breaks
16:30:31 <acozine> understood, and that's definitely something that documentation can help with, if not fix
16:30:51 <acozine> thanks folks!
16:30:57 <acozine> add stuff to the agenda for next week!
16:31:06 <acozine> #endmeeting