New policies for Extras Modules

Archives Ansible Project
1

First, thanks to all who have participated in recent discussions
around our development practices on ansible-devel, which have been
productive and helpful.

Now it's time to make some decisions. With the release of Ansible 2.0
coming soon, we'd like to make some policy changes around the
maintenance of the ansible-modules-extras repository.

First: module owners will assume all responsibility for managing their
own modules. Each module owner will manage their own forks of the
ansible-modules-extras repo; any pull requests from those repos to
update their own modules will be auomatically merged, without further
review.

Example: Bob owns the yaktalk module
(ansible/ansible-modules-extras/notifications/yaktalk.py). Someone
finds a documentation bug in the yaktalk module and submits a PR
against the ansible repo. Bob would then check the PR,
comment/iterate as necessary, and when Bob is happy, he would merge it
into his own repo
(bob/ansible-modules/extras/notifications/yaktalk.py) and then submit
the PR from his own repo. Because we know that Bob is the owner of
yaktalk, we would merge the pull request.

Second: new modules from owners of existing modules will have their
modules automatically approved and merged, since we assume that owners
of existing modules know the conventions for module development.

Third: new modules from new submitters will go through a period of
review, to ensure that the submitters are following the appropriate
conventions for module development.

Finally: a new Ansible Extras package will be split out from the main
Ansible package.

The goal of these changes is to ensure that the people who are the
closest to the modules themselves are responsible for their ongoing
maintenance, and to allow a bit more leeway so that the Ansible team
isn't a bottleneck.

This leaves some open questions that we'll need to sort out:

* How will we know who the module owner is? One option: we ask owners
to put their names and github IDs into the module itself. Another
option: we keep an external database linking owners to their modules.

* How will module owners be notified of PRs/issues against their
modules? Matt Martz has a tool that will allow people to subscribe to
notifications to their modules; we can use that or something similar.

* How do module owners hand off their modules to someone else, or
"orphan" a module entirely? In the short term, an email to the
ansible-devel mailing list is probably sufficient.

* What happens if a module owner fails to maintain their modules in a
timely manner? Ultimately, we may reserve the right to deprecate a
module that is persistently broken and who has an unresponsive
maintainer.

* When will this policy go into effect? Immediately upon working out
all open issues.

Comments/feedback encouraged.

--g

2

​This sounds good.​

This leaves some open questions that we'll need to sort out:

* How will we know who the module owner is? One option: we ask owners
to put their names and github IDs into the module itself. Another
option: we keep an external database linking owners to their modules.

​Depends I guess on the options on how to parse things and to trigger
github.
Having some ID in the module itself would have the advantage to easily
delegate that,
when necessary, core maintainers can also easily change it.
​

* How will module owners be notified of PRs/issues against their
modules? Matt Martz has a tool that will allow people to subscribe to
notifications to their modules; we can use that or something similar.

! ​Keep in mind that the "maintainer" might be a Github organisation​

​and not a lone developer,
​

* How do module owners hand off their modules to someone else, or
"orphan" a module entirely? In the short term, an email to the
ansible-devel mailing list is probably sufficient.

​If the ID is maintained within the module, the original owner can easily
change it.
​

* What happens if a module owner fails to maintain their modules in a
timely manner? Ultimately, we may reserve the right to deprecate a
module that is persistently broken and who has an unresponsive
maintainer.

​​If the ID is maintained within the module, a core maintainer can easily
change it.​

​ Serge​

3

Hey Greg,

“Example: Bob owns the yaktalk module
(ansible/ansible-modules-extras/notifications/yaktalk.py). Someone
finds a documentation bug in the yaktalk module and submits a PR
against the ansible repo. Bob would then check the PR,
comment/iterate as necessary, and when Bob is happy, he would merge it
into his own repo
(bob/ansible-modules/extras/notifications/yaktalk.py) and then submit
the PR from his own repo. Because we know that Bob is the owner of
yaktalk, we would merge the pull request.”

  1. Who gets credit on github for the merge, Bob or the original author of the PR. (Credit on Github being the stats at https://github.com/ansible/ansible-modules-extras/graphs/contributors and https://github.com/ansible/ansible-modules-extras/commits/devel/database/mysql/mysql_replication.py for example)
  2. What happens to the original PR against ansible, does it get closed unmerged? Who is closing it, bcoca? is bcoca expected to comb through all the open requests, find ones where Bob submitted an identical PR and got it merged?
  3. Is this a hard and fast rule? Will 100% nothing get updated without Bob’s approval for his module? Can bcoca/abadger merge things were Bob was unresponsive / did not see the value in the request?
  4. Why do you believe the additional walls this creates will speed up merge requests faster than say Bob commenting on the original PR and saying it looks good to him?

Thank you,
Jon

4

Hi

May I answer some parts of this question:

  1. Who gets credit on github for the merge, Bob or the original author of the PR. (Credit on Github being the stats at https://github.com/ansible/ansible-modules-extras/graphs/contributors and https://github.com/ansible/ansible-modules-extras/commits/devel/database/mysql/mysql_replication.py for example)

Git does make a difference between an author and a committer, So this information will remain in the commit.

  1. What happens to the original PR against ansible, does it get closed unmerged? Who is closing it, bcoca? is bcoca expected to comb through all the open requests, find ones where Bob submitted an identical PR and got it merged?

The commiter should take care by adding a “closes GH-”. When ansible inc merges the PR of the module author, the origin will also be closed as well.

5

Hi Greg

Just wanted to say, I like this new workflow!

First: module owners will assume all responsibility for managing their
own modules. Each module owner will manage their own forks of the
ansible-modules-extras repo; any pull requests from those repos to
update their own modules will be auomatically merged, without further
review.

+1

Second: new modules from owners of existing modules will have their
modules automatically approved and merged, since we assume that owners
of existing modules know the conventions for module development.

Sound good!

Third: new modules from new submitters will go through a period of
review, to ensure that the submitters are following the appropriate
conventions for module development.

Who will review? Ansible Inc or are existing owners also be able to review and give +1 for a merge?

Finally: a new Ansible Extras package will be split out from the main
Ansible package.

So this package can be updated outside the ansible release cycle right? Also think about the module_utils dependencies if we have 2 packages.

This leaves some open questions that we'll need to sort out:

* How will we know who the module owner is? One option: we ask owners
to put their names and github IDs into the module itself. Another
option: we keep an external database linking owners to their modules.

I really see no benefit of an external database.

So I am for the github id inside the module. As maintainers have likely a fork of the repo in their github accounts. We could also think about pointing a notice to make the PR to the maintainers repo.

Git is distributed, there are many ways.

* How will module owners be notified of PRs/issues against their
modules? Matt Martz has a tool that will allow people to subscribe to
notifications to their modules; we can use that or something similar.

That would be great.

* How do module owners hand off their modules to someone else, or
"orphan" a module entirely? In the short term, an email to the
ansible-devel mailing list is probably sufficient.

Sounds reasonable.

* What happens if a module owner fails to maintain their modules in a
timely manner? Ultimately, we may reserve the right to deprecate a
module that is persistently broken and who has an unresponsive
maintainer.

We will not be able to handle every corner cases. But that's okay. Exising owners of other modules could take over or owners of the "section" like "/cloud" could be notified. In any case, the mailing list is the last help.

It remainds me a bit of this https://www.youtube.com/watch?v=L2SED6sewRw&t=5m10s

and especially this part https://www.youtube.com/watch?v=L2SED6sewRw&t=7m30s

* When will this policy go into effect? Immediately upon working out
all open issues.

Awesome!

Yours
René

6

Hi Greg

Hi Rene. Thanks for your feedback. Some comments to particular bits:

<snip>

Third: new modules from new submitters will go through a period of
review, to ensure that the submitters are following the appropriate
conventions for module development.

Who will review? Ansible Inc or are existing owners also be able to review
and give +1 for a merge?

This is a good question.

My inclination is to be fairly strict on new submitters, but that
doesn't mean that it has to be only Ansible employees who can approve
new submitters.

Maybe for now: 2 +1s from any module owner, and any -1s must be
resolved? (Or someone from Ansible can just bless; we should reserve
the right to do that in some cases.)

Ultimately, I'd like to move to a model where every module owner is
also a committer in Extras. I want to put enough structure in place so
that if/when we make the decision to allow module owners to commit
directly, we have a high degree of confidence that they'll be Doing
The Right Things (tm).

Finally: a new Ansible Extras package will be split out from the main
Ansible package.

So this package can be updated outside the ansible release cycle right? Also
think about the module_utils dependencies if we have 2 packages.

For now, we're going to keep the release schedules in sync, but from
my perspective, a rolling release of Extras is the eventual goal.
Small steps. :slight_smile:

This leaves some open questions that we'll need to sort out:

* How will we know who the module owner is? One option: we ask owners
to put their names and github IDs into the module itself. Another
option: we keep an external database linking owners to their modules.

I really see no benefit of an external database.

So I am for the github id inside the module. As maintainers have likely a
fork of the repo in their github accounts. We could also think about
pointing a notice to make the PR to the maintainers repo.

Git is distributed, there are many ways.

Yeah. I'm inclined to say "owner is a field in the module
documentation" but open to hear counter-arguments. At some point we'll
just make a decision.

* How will module owners be notified of PRs/issues against their
modules? Matt Martz has a tool that will allow people to subscribe to
notifications to their modules; we can use that or something similar.

That would be great.

Go test his tool: https://ansible.sivel.net/

(It ISEs for me right now, but I appear to be an anomalous case, and
Mr. Martz is aware.)

* How do module owners hand off their modules to someone else, or
"orphan" a module entirely? In the short term, an email to the
ansible-devel mailing list is probably sufficient.

Sounds reasonable.

* What happens if a module owner fails to maintain their modules in a
timely manner? Ultimately, we may reserve the right to deprecate a
module that is persistently broken and who has an unresponsive
maintainer.

We will not be able to handle every corner cases. But that's okay. Exising
owners of other modules could take over or owners of the "section" like
"/cloud" could be notified. In any case, the mailing list is the last help.

It remainds me a bit of this
https://www.youtube.com/watch?v=L2SED6sewRw&t=5m10s

Yeah. I think this does owe a lot to the Linux lieutenant model. I
don't think we need that complexity yet, but the general model is
obviously sound.

and especially this part https://www.youtube.com/watch?v=L2SED6sewRw&t=7m30s

* When will this policy go into effect? Immediately upon working out
all open issues.

Next step: over the next couple of days, I'll be going through every
Extras PR and tagging some with "owner_pr" so we can get a good look
at what we're actually proposing, what impact it'll have, and so on.
We've already got a tag for "new_module". I'll report back with
findings later this week, and for next week's devel hangout I'd like
to go through those.

Should also put together a lightweight project plan somewhere for
this. I'll work on that too.

--g

7

we already have a 'author' field in module docs

8

Yep, which generally contains name and email. Should github id be an
addition or a replacement to email address?

--g

9

First, thanks to all who have participated in recent discussions
around our development practices on ansible-devel, which have been
productive and helpful.

Now it’s time to make some decisions. With the release of Ansible 2.0
coming soon, we’d like to make some policy changes around the
maintenance of the ansible-modules-extras repository.

First: module owners will assume all responsibility for managing their
own modules. Each module owner will manage their own forks of the
ansible-modules-extras repo; any pull requests from those repos to
update their own modules will be auomatically merged, without further
review.

Example: Bob owns the yaktalk module
(ansible/ansible-modules-extras/notifications/yaktalk.py). Someone
finds a documentation bug in the yaktalk module and submits a PR
against the ansible repo. Bob would then check the PR,
comment/iterate as necessary, and when Bob is happy, he would merge it
into his own repo
(bob/ansible-modules/extras/notifications/yaktalk.py) and then submit
the PR from his own repo. Because we know that Bob is the owner of
yaktalk, we would merge the pull request.

Second: new modules from owners of existing modules will have their
modules automatically approved and merged, since we assume that owners
of existing modules know the conventions for module development.

Third: new modules from new submitters will go through a period of
review, to ensure that the submitters are following the appropriate
conventions for module development.

Finally: a new Ansible Extras package will be split out from the main
Ansible package.

The goal of these changes is to ensure that the people who are the
closest to the modules themselves are responsible for their ongoing
maintenance, and to allow a bit more leeway so that the Ansible team
isn’t a bottleneck.

This leaves some open questions that we’ll need to sort out:

  • How will we know who the module owner is? One option: we ask owners
    to put their names and github IDs into the module itself. Another
    option: we keep an external database linking owners to their modules.

Can we put them into meta/main.yml with original repo-name. As this would
allow ansible-galaxy detect original module name without depending on
directory name in which module is.

10

Having just gone through several dozen PRs, I now strongly believe
that this information needs to be in the module metadata itself.
Separate longer analysis coming soon.

--g