Skip to content
This repository has been archived by the owner on May 14, 2024. It is now read-only.

Making community docs a separate project to ansible/ansible #243

Closed
samccann opened this issue Jun 13, 2023 · 17 comments
Closed

Making community docs a separate project to ansible/ansible #243

samccann opened this issue Jun 13, 2023 · 17 comments
Assignees

Comments

@samccann
Copy link

Summary

This issue proposes to separate the source content for Ansible community documentation published at docs.ansible.com/ansible and docs.ansible.com/ansible-core from the ansible/ansible repository.

This proposal is intended to benefit the Ansible community by decoupling community doc initiatives from core release cycles. Additionally this proposal removes the Ansible Core team as the gate for other changes that will meet community needs, such as putting source content for docs.ansible.com under the direct control of the Steering Committee.

It is a first step towards providing greater access and ownership of docs.ansible.com to the Ansible community.

Summarized details

The Ansible core team is facilitating a lift and shift of docs/docsite from ansible/ansible to ansible/ansible-documentation. This is an interim step toward full community/Steering committee control of Ansible package documentation.

Testing and feedback timeframe

To ensure community members have time to evaluate and ‘test drive’ this proposed solution, we have the ansible/ansible-documentation repository up and running with a jenkins job. We will use this repo starting on Thursday, June 15th, for a two week period - ending June 29th, 2023.

All docs PRs will happen in the new repository during this test period and be published regularly to devel docs to see if we come across any technical glitches.

Full details

See #240 for discussion on some of the drivers for this change as well as https://hackmd.io/@ansible-community/rkzSKCEvh for the nitty gritty details.

Additional Information

No response

@samccann
Copy link
Author

If you are trying the docs build locally on this new repo, you need one more step:
python3 docs/bin/clone-core.py

We'll find an appropriate place to document that but just fyi.

@gotmax23
Copy link
Contributor

Thanks for typing up this proposal. I have one question. The proposal says:

this proposal removes the Ansible Core team as the gate for other changes that will meet community needs, such as putting source content for docs.ansible.com under the direct control of the Steering Committee.

but the rest of it only talks about the ansible/ansible-documentation repository which is not under the control of the SC.

@oraNod
Copy link

oraNod commented Jun 14, 2023

@gotmax23 This proposal is intended to offer a first step towards the SC gaining full control of source files to resolve #240

There are quite a few strands in here - e.g. the new repo includes a fully functional copy of the hacking folder - and taking an incremental approach safeguards docs.ansible. Ultimately the lift and shift will give a lot more flexibility and autonomy for the Ansible community.

I'll update that hackMD. Cheers.

@samccann samccann removed the next_meeting Topics that needs to be discussed in the next Community Meeting label Jun 14, 2023
@sakeleo213
Copy link

sakeleo213 commented Jun 17, 2023

Thank You for typing This Proposal.
GTA 5 Android Apk OBB

@acozine
Copy link
Contributor

acozine commented Jun 22, 2023

There are advantages to having community ownership of community documentation.

However, there are serious disadvantages to having the documentation in a separate repo from the code. A separate docs repo makes it harder to require documentation for every new feature, and easier to forget to update the documentation in general.

We've discussed this in the DaWGs meeting, but I wanted this ticket to reflect the conversation as well.

@samccann
Copy link
Author

Something else that came up - today, the core team keeps an eye on all issues and fixes many docs issues since they show up in the core triage/backlog etc. We'd want to ensure that level of stewardship continues in the new docs repo.

@oraNod
Copy link

oraNod commented Jun 27, 2023

@gotmax23 We've been looking into settings with the new repo. It does look like we have the ability to add Steering Committee members more access to ansible/ansible-documentation:

image

Does this look like it would address the issue around access to docs? Or do you think it would be preferable to move a subset of content into the ansible-community org? Thanks.

@gotmax23
Copy link
Contributor

I think giving at least some SC members commit on ansible/ansible-documentation is a good start. We can look into moving specific things out later.

@oraNod
Copy link

oraNod commented Jun 29, 2023

@gotmax23 What do you think about creating a "steering committee" team here? https://github.com/orgs/ansible/teams

That way we can grant access to the team and add/remove folks from the team. Preferably someone in the SC could create and populate the team.

@gotmax23
Copy link
Contributor

That sounds good to me. I'm not sure whether I have sufficient privs, but let me know how I can help.

@oraNod
Copy link

oraNod commented Jul 3, 2023

@gotmax23 and @felixfontein To start I've added you both as maintainers to a new team: https://github.com/orgs/ansible/teams/steering-committee

I've also added this team with maintainer access to the https://github.com/ansible/ansible-documentation repository.

Please let me know if that works OK or if you have any other thoughts to improve. I can add more folks to the team as well, if you think we should go ahead. Cheers.

@felixfontein
Copy link
Contributor

I tried to add all @ansible-community/steering-committee members to @ansible/steering-committee, but I couldn't add Alexei, Brian, Mario, Markus, and James as they aren't members of the @ansible organization. I don't know who can change this...

@gotmax23
Copy link
Contributor

gotmax23 commented Jul 9, 2023

I don't know who can change this...

@gundalow or anyone else in https://github.com/orgs/ansible/people?query=role%3Aowner.

@gundalow gundalow self-assigned this Jul 11, 2023
@gotmax23 gotmax23 added the next_meeting Topics that needs to be discussed in the next Community Meeting label Jul 12, 2023
@samccann samccann removed the next_meeting Topics that needs to be discussed in the next Community Meeting label Jul 19, 2023
@oraNod oraNod added implemented and removed discussion_topic being_implemented This is currently being implemented labels Aug 9, 2023
@oraNod
Copy link

oraNod commented Aug 9, 2023

@samccann Think we're good to close this one?

@samccann
Copy link
Author

samccann commented Aug 9, 2023

Did the people with missing rights from #243 (comment) get added?

@oraNod
Copy link

oraNod commented Aug 10, 2023

Hmm. No, I think we need to wait on @gundalow for that (still on PTO for another while). What if we break that into a separate topic because it's kind of tangential to this one? That might also provide an opportunity to revisit the steering committee membership.

@samccann
Copy link
Author

@gundalow assigned this issue to himself so if you do create another issue (maybe on the community-team repo as it doesn't need discussion) to update the membership, then assign it to him pls so it shows up on his radar.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

7 participants