MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1315

Devids10 · 2024-04-24T07:09:09Z

This is a solution for the issue #1129.

…n next to playbooks

ansible-documentation-bot · 2024-04-24T07:09:44Z

Thanks for your Ansible docs contribution! We talk about Ansible documentation on matrix at #docs:ansible.im and on libera IRC at #ansible-docs if you ever want to join us and chat about the docs! We meet there on Tuesdays (see the Ansible calendar) and welcome additions to our weekly agenda items - scroll down to find the upcoming agenda and add a comment to put something new on that agenda.

oraNod · 2024-04-24T08:05:56Z

docs/docsite/rst/collections_guide/collections_installing.rst

+Installing collections adjacent to playbooks
+--------------------------------------------
+
+.. include:: ../shared_snippets/installing_collections_playbooks.txt


Hi @Devids10 I think the idea is to get rid of the shared snippets .txt file and put the content directly in the .rst file.

…n anchor to the new section

Devids10 · 2024-04-24T18:07:08Z

@oraNod I think this is what you all were thinking about.
(Ignore all the pushes, I forgot to add files to the commit)

oraNod

Looks better @Devids10 Thanks for the updates. Left some comments.

docs/docsite/rst/collections_guide/collections_installing.rst

oraNod · 2024-04-25T09:31:33Z

docs/docsite/rst/collections_guide/collections_installing.rst

+--------------------------------------------
+
+You can install collections locally next to your playbooks inside your project instead of in a global location on your system or on your AWX.
+This approach has these added benefits:


Suggested change

This approach has these added benefits:

Using locally installed collections adjacent to playbooks has some benefits, such as:

Please add an empty line above this to separate it from the first sentence.

oraNod · 2024-04-25T09:32:49Z

docs/docsite/rst/collections_guide/collections_installing.rst

+
+You can install collections locally next to your playbooks inside your project instead of in a global location on your system or on your AWX.
+This approach has these added benefits:
+* Ensures that all users of the project use the same collection version.


A tip with list items is to use parallelism. The starting verb in each list item should use the same tense.

docs/docsite/rst/collections_guide/collections_installing.rst

oraNod

LGTM. Thanks @Devids10

patchback · 2024-04-30T21:19:04Z

Backport to stable-2.15: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply ba04139 on top of patchback/backports/stable-2.15/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315

Backporting merged PR #1315 into devel

Ensure you have a local repo clone of your fork. Unless you cloned it
from the upstream, this would be your origin remote.
Make sure you have an upstream repo added as a remote too. In these
instructions you'll refer to it by the name upstream. If you don't
have it, here's how you can add it:
```
$ git remote add upstream https://github.com/ansible/ansible-documentation.git
```

Ensure you have the latest copy of upstream and prepare a branch
that will hold the backported code:

$ git fetch upstream
$ git checkout -b patchback/backports/stable-2.15/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315 upstream/stable-2.15

Now, cherry-pick PR MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1315 contents into that branch:
```
$ git cherry-pick -x ba04139aaa7a178eed1ccda037f962bea1dd5594
```
If it'll yell at you with something like fatal: Commit ba04139aaa7a178eed1ccda037f962bea1dd5594 is a merge but no -m option was given., add -m 1 as follows instead:
```
$ git cherry-pick -m1 -x ba04139aaa7a178eed1ccda037f962bea1dd5594
```
At this point, you'll probably encounter some merge conflicts. You must
resolve them in to preserve the patch from PR MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1315 as close to the
original as possible.

Push this branch to your fork on GitHub:

$ git push origin patchback/backports/stable-2.15/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315

Create a PR, ensure that the CI is green. If it's not — update it so that
the tests and any other checks pass. This is it!
Now relax and wait for the maintainers to process your pull request
when they have some cycles to do reviews. Don't worry — they'll tell you if
any improvements are necessary when the time comes!

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

patchback · 2024-04-30T21:19:29Z

Backport to stable-2.14: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply ba04139 on top of patchback/backports/stable-2.14/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315

Backporting merged PR #1315 into devel

Ensure you have a local repo clone of your fork. Unless you cloned it
from the upstream, this would be your origin remote.
Make sure you have an upstream repo added as a remote too. In these
instructions you'll refer to it by the name upstream. If you don't
have it, here's how you can add it:
```
$ git remote add upstream https://github.com/ansible/ansible-documentation.git
```

Ensure you have the latest copy of upstream and prepare a branch
that will hold the backported code:

$ git fetch upstream
$ git checkout -b patchback/backports/stable-2.14/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315 upstream/stable-2.14

Now, cherry-pick PR MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1315 contents into that branch:
```
$ git cherry-pick -x ba04139aaa7a178eed1ccda037f962bea1dd5594
```
If it'll yell at you with something like fatal: Commit ba04139aaa7a178eed1ccda037f962bea1dd5594 is a merge but no -m option was given., add -m 1 as follows instead:
```
$ git cherry-pick -m1 -x ba04139aaa7a178eed1ccda037f962bea1dd5594
```
At this point, you'll probably encounter some merge conflicts. You must
resolve them in to preserve the patch from PR MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1315 as close to the
original as possible.

Push this branch to your fork on GitHub:

$ git push origin patchback/backports/stable-2.14/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315

Create a PR, ensure that the CI is green. If it's not — update it so that
the tests and any other checks pass. This is it!
Now relax and wait for the maintainers to process your pull request
when they have some cycles to do reviews. Don't worry — they'll tell you if
any improvements are necessary when the time comes!

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

patchback · 2024-04-30T21:19:48Z

Backport to stable-2.16: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-2.16/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315

Backported as #1380

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

…1129 (#1315) * feat: remove the reused snippet * feat: add new shared_snippet and add description of local installation next to playbooks * feat: add new section for installing collections locally * fix: fix nox check error * fix: remove shared txt files, add them to their included space, add an anchor to the new section * fix: comments from the pull request --------- Co-authored-by: Dávid Németh <[email protected]> (cherry picked from commit ba04139)

patchback · 2024-04-30T21:20:10Z

Backport to stable-2.17: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-2.17/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315

Backported as #1381

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

…1129 (#1315) * feat: remove the reused snippet * feat: add new shared_snippet and add description of local installation next to playbooks * feat: add new section for installing collections locally * fix: fix nox check error * fix: remove shared txt files, add them to their included space, add an anchor to the new section * fix: comments from the pull request --------- Co-authored-by: Dávid Németh <[email protected]> (cherry picked from commit ba04139)

samccann · 2024-04-30T21:25:07Z

This is great, thanks! I opened #1315 to review and remove some more of these shared snippets. I put the muni writers label on it, but I don't know if there's still time in the schedule for folks to take that one on.

…/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315 [PR #1315/ba04139a backport][stable-2.16] MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129

…/ba04139aaa7a178eed1ccda037f962bea1dd5594/pr-1315 [PR #1315/ba04139a backport][stable-2.17] MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129

Dávid Németh added 3 commits April 24, 2024 09:01

feat: remove the reused snippet

7f54dcf

feat: add new shared_snippet and add description of local installatio…

d80e37c

…n next to playbooks

feat: add new section for installing collections locally

50f4c9a

Devids10 temporarily deployed to github-bot April 24, 2024 07:09 — with GitHub Actions Inactive

ansible-documentation-bot bot added the new_contributor This PR is the first contribution by a new community member. label Apr 24, 2024

Devids10 marked this pull request as draft April 24, 2024 07:11

fix: fix nox check error

a2641f4

Devids10 temporarily deployed to github-bot April 24, 2024 07:21 — with GitHub Actions Inactive

oraNod reviewed Apr 24, 2024

View reviewed changes

Devids10 temporarily deployed to github-bot April 24, 2024 17:56 — with GitHub Actions Inactive

Devids10 force-pushed the better_documented_local_collections branch from ace8404 to a2641f4 Compare April 24, 2024 18:00

Devids10 temporarily deployed to github-bot April 24, 2024 18:00 — with GitHub Actions Inactive

fix: remove shared txt files, add them to their included space, add a…

385a15c

…n anchor to the new section

Devids10 temporarily deployed to github-bot April 24, 2024 18:04 — with GitHub Actions Inactive

Devids10 marked this pull request as ready for review April 24, 2024 18:06

oraNod reviewed Apr 25, 2024

View reviewed changes

oraNod requested review from felixfontein and samccann April 25, 2024 09:33

samccann reviewed Apr 25, 2024

View reviewed changes

docs/docsite/rst/collections_guide/collections_installing.rst Outdated Show resolved Hide resolved

docs/docsite/rst/collections_guide/collections_installing.rst Outdated Show resolved Hide resolved

fix: comments from the pull request

060fde7

Devids10 temporarily deployed to github-bot April 25, 2024 21:27 — with GitHub Actions Inactive

oraNod approved these changes Apr 30, 2024

View reviewed changes

oraNod requested a review from samccann April 30, 2024 14:39

samccann approved these changes Apr 30, 2024

View reviewed changes

samccann merged commit ba04139 into ansible:devel Apr 30, 2024
8 checks passed

patchback bot mentioned this pull request Apr 30, 2024

[PR #1315/ba04139a backport][stable-2.16] MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1380

Merged

patchback bot mentioned this pull request Apr 30, 2024

[PR #1315/ba04139a backport][stable-2.17] MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1381

Merged

samccann mentioned this pull request Apr 30, 2024

Incorporate 'shared snippets' for the collection docs into the main rst files #1382

Open

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1315

MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1315

Devids10 commented Apr 24, 2024

ansible-documentation-bot bot commented Apr 24, 2024

oraNod Apr 24, 2024

Devids10 commented Apr 24, 2024

oraNod left a comment

oraNod Apr 25, 2024

oraNod Apr 25, 2024

oraNod Apr 25, 2024

oraNod left a comment

patchback bot commented Apr 30, 2024 •

edited

Loading

patchback bot commented Apr 30, 2024 •

edited

Loading

patchback bot commented Apr 30, 2024 •

edited

Loading

patchback bot commented Apr 30, 2024 •

edited

Loading

samccann commented Apr 30, 2024

	This approach has these added benefits:
	Using locally installed collections adjacent to playbooks has some benefits, such as:

MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1315

MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 #1315

Conversation

Devids10 commented Apr 24, 2024

ansible-documentation-bot bot commented Apr 24, 2024

oraNod Apr 24, 2024

Choose a reason for hiding this comment

Devids10 commented Apr 24, 2024

oraNod left a comment

Choose a reason for hiding this comment

oraNod Apr 25, 2024

Choose a reason for hiding this comment

oraNod Apr 25, 2024

Choose a reason for hiding this comment

oraNod Apr 25, 2024

Choose a reason for hiding this comment

oraNod left a comment

Choose a reason for hiding this comment

patchback bot commented Apr 30, 2024 • edited Loading

Backport to stable-2.15: 💔 cherry-picking failed — conflicts found

Backporting merged PR #1315 into devel

patchback bot commented Apr 30, 2024 • edited Loading

Backport to stable-2.14: 💔 cherry-picking failed — conflicts found

Backporting merged PR #1315 into devel

patchback bot commented Apr 30, 2024 • edited Loading

Backport to stable-2.16: 💚 backport PR created

patchback bot commented Apr 30, 2024 • edited Loading

Backport to stable-2.17: 💚 backport PR created

samccann commented Apr 30, 2024

patchback bot commented Apr 30, 2024 •

edited

Loading

patchback bot commented Apr 30, 2024 •

edited

Loading

patchback bot commented Apr 30, 2024 •

edited

Loading

patchback bot commented Apr 30, 2024 •

edited

Loading