This has come up in different discussions recently. To give a bit of background, we moved the docs out of ansible/ansible and into ansible/ansible-documentation about a year ago, to allow docs to iterate quickly and extend maintainer rights to more community members.
Even right after that move, we started getting requests to move some docs to ansible-community so the Steering Committee can have full ownership. And again here, and most recently… here and here.
The driving factor seems to be the community team has full admin rights to the ansible-community GitHub org, but (for good reasons) not the Ansible org.
Proposal - move ansible-documentation repo to ansible-community/ansible-documentation repo.
Benefits - full rights to add maintainers, as well as full steering committee as a new github group to help with labeling PRs under their approval etc.
Drawbacks - We just moved this a year ago, is it confusing to move it again?
I don’t know if there are other implications to moving the repo, so please do discuss here and we’ll eventually have a poll to see what folks think.
Another drawback: it’s pretty hard to move issues from ansible/ansible to ansible-community/ansible-documentation.
(Moving issues inside one organization is easy assuming you have sufficient access to both the source and destination repo. Moving them across organizations isn’t directly possible; you can move them to a ‘move’ repo, move that repo to the other organization, and then move the issue from that repo to the destination repo. But that’s annoying and only worth the effort for once-in-a-time bulk moves.)
yes, for ansible/ansible issues, we’d have to manually recreate on ansible-community/ansible-documentation and then close the old issue with a pointer to the new. I haven’t been paying attention of late, but I’d guess we have less than two of these a month?
If we move ansible-documentation to a new org, do all the open issues and prs come with it?
When most modules have been moved to collections some time ago, a lot of issues have been closed in ansible and re-opened in the (new) collection with a reference to the original issue IIRC. For example VMware: Unable to create vSphere Cluster in idempotent manner which states Copied from original issue: ansible/ansible#64354. We could do the same here, but it would be a lot of work.
It could be scripted. I’m reasonably familiar with the GitHub API at this point, and Issues are relatively simple (no attached code) so it would, I think, be a matter of reading the first post of the issue, and then writing it to a new issue in the new repo with a link to the old, and setting some tags.
The issues that were copied with notes such as Copied from original issue: ansible/ansible#xxx were (mostly?) automatically copied, IIRC. I think the script for copying them was available somewhere, but I forgot where. Maybe @Akasurde remembers since I think he did a lot of issue copying back then?
fwiw, when we did the plugin splits to and from ansible-plugins-core/extras, we found that the majority of the issues/prs we moved became unmonitored by the original author. Not by any actual technical mechanism, but many were drive by contributions, and we ultimately just closed a vast majority of them.
The core team isn’t likely to run any script like the bot to move them, and not likely to grant permissions for another bot maintained by someone outside of core to close issues and PRs.
Our operating mechanism would be to just close them, and tell people where the new repo is. As it is, we move very few, and I’m probably the only one who has done it due to permission requirements.
I brought this discussion up in general with the core team, and while I thought I remembered this, I got confirmation there was a prior agreement that we would not move the repo to another org, until the docs were split into separate repos between core and community.
I suppose it’s not a deal breaker, but note that there is still the expectation that all core docs get removed from the community owned repository, and the repository split into 2. This would require however, potentially moving part of the repo back to the ansible org at a later date.
So due to this, I am leaning toward making it a requirement that the docs repo be split before migrating it to a new org to reduce churn.
Thanks for the update… glad someone has a memory cuz I sure don’t! But this does sound familiar. So if I’m understanding things:
core project has core docs (either in the current repo or moved back to ansible/ansible)
Package ‘project’ has package docs (in a new repo in the ansible-community org).
I think the difficulty here is that the community package docs and the core docs have …oh I’ll randomly say 80% direct reuse of the same content. So if we split the docs repo, we’d need:
a package publishing effort that would grab the core docs and core plugins (maybe an enhancement of the existing clone )
Core taking responsibility for the core docs merges etc (no one else has rights to merge in ansible/ansible anymore)
I think we risk losing the ‘edit on github’ for the package docs if those files exist in a separate repo. I don’t know if there is a way in sphinx to keep that across two repos. Alternately, we remove it from the package-specific docs. Most of them are under Steering Committee control and can’t be changed w/o approval so maybe we can do without the simple way to edit those?
In the DaWGs meeting last week, we decided: To stay in the current repo and fix steering committee rights as needed. Other options seem to have a negative impact on our contributors without significant benefits.
I will followup with core folks to determine what the goal is behind moving core docs back into the ansible/ansible repo.
