12:58 p.m.
Hey All,
A few comments. Currently github.com/containers/podman.io does not
have CI checking, that may be something that we change in the future.
So the barrier to entry in making a PR there is lower than to the Podman
GitHub repository.
One thing to consider about moving the docs from podman to
podman.io is indeed the CI checking in podman. In addition to the CI
checking for new tests, only docs, etc., the CI also checks to make sure
that if a new option is added, either to a man page or to the code, then
it must be in both places or the PR fails the smoke test. That's
something that would be hard to emulate if the docs were across two
projects, so we'd lose that functionality. Perhaps the payback from the
move pays for that loss, IDK. I do know that we've had a few instances
of the CI failing a PR due to the man page not being updated.
All that said, I'm not against the moved. From a logical
standpoint, it makes sense to me that you'd find the docs in
'docs.podman.io' in the podman.io project.
t
On 9/18/21 8:37 AM, Daniel Walsh wrote:
On 9/17/21 11:15, Leon N wrote:
> Hi,
>
> This sounds really cool, I'd love to be a part of it.
>
> Regards,
> Leon
>
> On Fri, 17 Sep, 2021, 20:32 Scott McCarty, <smccarty(a)redhat.com> wrote:
>
> All,
> I chatted with Mehul today and I want to start a
> conversation around how we could improve the docs. Here are my
> thoughts:
>
BTW, we did do some fixes to clean up the commands parts of the docs,
this past week.
>
> 1. Figure out a way to keep the main page canonical sources on
> https://github.com/containers/podman/tree/main/docs/source/markdown
> 2. Synchronize
> https://github.com/containers/podman/docs/source/markdown
>
<https://github.com/containers/podman/tree/main/docs/source/markdown> to
> github.com/containers/podman.io/docs/source/markdown
> <http://github.com/containers/podman.io/docs>
> 3. Let's move everything else from
> github.com/containers/podman/docs
> <http://github.com/containers/podman/docs/source/markdown> over
> to the github.com/containers/podman.io/docs
> <http://github.com/containers/podman.io/docs>
> 4. Update the theme to this new theme Mehul tested [1] call
> furo. Feel free to test that container image. It pulls the
> content from the current repository.
> 5. If we do #3, we can make it easier for people to commit docs
> because it wouldn't need to go through the full CI/CD gating
> tests (might not be correct. Is the podman.io
> <http://podman.io> repository gated by the same CI/CD?)
> 6. Second, we could have dedicated editors instead of engineers
> approve docs changes
>
Difficult to implement. I don't want PRs being blocked, because we
can't get DOC editors to approve man page changes.
>
> An alternative to this proposal could be to use a completely new
> repository apart from podman.io <http://podman.io>;. If we can
> separate the docs out, I think we could find volunteers to be
> editors (aka approve PRs). This would allow core code
> contributors to focus on code, and docs volunteers to focus on
> docs. Stated another way, I don't think docs needs CI/CD like
> code. I think editors probably do a better job (though CI/CD
> could be useful for link checking, etc).
>
Not sure how you handle man pages, which are the core piece of Docs,
but updated all of the time by engineers.
>
>
> Thoughts?
>
>
> [1]:
> FROM fedora:latest
>
> EXPOSE 8000
> RUN dnf install -y gpgme-devel \
> libseccomp-devel.x86_64 \
> systemd-devel \
> make \
> git \
> golang \
> python \
> && export PKG_CONFIG_PATH="/usr/lib/pkgconfig"
>
>
> RUN cd / && git clonehttps://github.com/containers/podman.git \
> && cd podman \
> && make install.tools
>
> RUN cd /podman/docs \
> && dnf -y install python3-sphinx python3-recommonmark \
> && pip install sphinx-markdown-tables furo \
> && sed -i 's|html_theme = "alabaster"|html_theme =
"furo"|g' /podman/docs/source/conf.py \
> && make html
>
> WORKDIR /podman/docs
>
> CMD ["python", "-m", "http.server",
"8000", "--directory", "build/html"]
>
>
>
> Best Regards
> Scott M
>
> --
>
> --
>
> 18 ways to differentiate open source products from upstream
suppliers:https://opensource.com/article/21/2/differentiating-products-up...
> --
>
> Scott McCarty Product Management - Containers, Red Hat Enterprise
> Linux & OpenShift Email: smccarty(a)redhat.com Phone: 312-660-3535
> Cell: 330-807-1043 Web: http://crunchtools.com
>
> _______________________________________________
> Podman mailing list -- podman(a)lists.podman.io
> To unsubscribe send an email to podman-leave(a)lists.podman.io
>
>
> _______________________________________________
> Podman mailing list --podman(a)lists.podman.io
> To unsubscribe send an email topodman-leave(a)lists.podman.io
_______________________________________________
Podman mailing list -- podman(a)lists.podman.io
To unsubscribe send an email to podman-leave(a)lists.podman.io