https://pantsbuild.org/ logo
#development
Title
# development
c

curved-television-6568

03/07/2023, 3:11 AM
can someone with API keys to readme.com update the 2.16 docs from
main
?
e

enough-analyst-54434

03/07/2023, 3:32 AM
In process ...
Done.
🙏 1
Hrm. So Tom updated the changelog.md: https://github.com/pantsbuild/pants/pull/18428/files But that did not update in a doc push. Presumably all docs/markdown need to have their header updatedAt manually bumped in any PR that touches them to get published?
If so that definitely is not awesome / a footgun.
👀 1
h

happy-kitchen-89482

03/07/2023, 6:06 PM
It's bigger than that - right now docs publishing is completely manual
And happens from release branches, so I have a cherrypick out right now for that one
bigger footgun, I mean
e

enough-analyst-54434

03/07/2023, 6:14 PM
Yeah, I was the one who ran the doc push yesterday and observed things like pip_version in the reference actually update but changelog not after I pushed (published).
I am very confused about docs publishing apparently. Are there steps not listed here?: https://www.pantsbuild.org/docs/release-process#step-2-update-this-docs-site I've finally read the code
build-support/bin/generate_docs.py
and it appears that just updates references. Do we need to be doing this thing too?: https://github.com/pantsbuild/pants/blob/main/docs/NOTES.md#sync-docs-changes-up-to-readmecom
f

fast-nail-55400

03/07/2023, 7:53 PM
Any reason we cannot use it?
e

enough-analyst-54434

03/07/2023, 7:53 PM
@ancient-vegetable-10556 do you know what's up here? I'm with Tom but also clearly we're not using that GH action currently. I'm confused about the current state of affairs getting docs published.
h

happy-kitchen-89482

03/07/2023, 8:08 PM
Ah, so maybe this is the source of confusion: there are two unrelated publish steps.
build-support/bin/generate_docs.py
generates option reference docs and can sync them up to readme.com. And there are instructions under
docs/
for how to sync the human-authored markdown in that dir.
Really we'd want to automate both as part of CI
a

ancient-vegetable-10556

03/07/2023, 8:08 PM
https://github.com/pantsbuild/pants/issues/18437 is (in actuality) a proposal to do just that
e

enough-analyst-54434

03/07/2023, 8:10 PM
And there are instructions under
docs/
for how to sync the human-authored markdown in that dir.
Was this known by people generally?
a

ancient-vegetable-10556

03/07/2023, 8:10 PM
@enough-analyst-54434 answering your question presently
e

enough-analyst-54434

03/07/2023, 8:10 PM
I always assumed the releaser instructions were complete.
a

ancient-vegetable-10556

03/07/2023, 8:10 PM
We didn’t invest in better tooling at the time we did the project because it was a PoC to see if in-repo docs made sense, without moving away from readme.com. I’d rather we were using Sphinx and e.g. readthedocs.com and have a proper 100% git/CI-driven process
I always assumed the releaser instructions were complete.
Basically, the in-repo non-reference docs is an experimental process that @happy-kitchen-89482, @hundreds-father-404, and I were handling on our own, that turned out to be an Actually Better way of doing things, that we just haven’t formalised into the release process yet.
e

enough-analyst-54434

03/07/2023, 8:12 PM
Ok, that's a big gap then. I had no idea.
a

ancient-vegetable-10556

03/07/2023, 8:12 PM
(it replaced another thing that wasn’t managed formally as part of the release process, so it’s not a huge loss
we just can’t assign the whole maintainers group to have readme.com access because it costs $4000 to have more than x editors there (and x is an unfeasibly small number)
e

enough-analyst-54434

03/07/2023, 8:14 PM
But the release process already says regen the reference /ask someone else. It should also say ditto for the docs/README step.
a

ancient-vegetable-10556

03/07/2023, 8:14 PM
that’s definitely doable.
e

enough-analyst-54434

03/07/2023, 8:14 PM
Yeah - this is a huge hole. Presumably no releasers save Benjy have been doing this at all this year?
a

ancient-vegetable-10556

03/07/2023, 8:15 PM
right
e

enough-analyst-54434

03/07/2023, 8:15 PM
K. Good to understand the mystery. Thanks.
a

ancient-vegetable-10556

03/07/2023, 8:17 PM
It’s worth nothing that we’ve confirmed the value of in-repo docs at this point. Cherry-picking across versions in particular is a huge gain for keeping the docs accurate. The question is whether we invest in better tooling for readme.com, or move to something that’s actually meant to handle in-repo docs. Would love to revisit the discussion sometime.
e

enough-analyst-54434

03/07/2023, 8:20 PM
It sounds like the investment is on the pennies level assuming Tom's GH action link works.
a

ancient-vegetable-10556

03/07/2023, 8:21 PM
not exactly, there’s some unfortunate source-of-truth related issues that come with readme, and need manual supervision, that don’t exist with RTD/sphinx
e

enough-analyst-54434

03/07/2023, 8:22 PM
So, the current doc/README has caveats? We can't just blindly sync?
a

ancient-vegetable-10556

03/07/2023, 8:22 PM
(if an external contributor suggests a change, a human needs to notice that, apply it to the Git source of truth, and publish it, rather than actually accepting the change suggestion
e

enough-analyst-54434

03/07/2023, 8:22 PM
My question basically is how the heck do we do this today
However that is - its getting skipped in releases. SOphinx goodness aside, that needs to be fixed now.
IOW there were commits to
doc/***/*.*md
that made it in in time for 2.16.0a0 that did not get synced to readme.com.
I want to ensure that is stop-gapped.
a

ancient-vegetable-10556

03/07/2023, 8:25 PM
currently some human with API access needs to manually branch the docs anyway
because our policy is that we don’t have the branch on readme until the release branch is cut
e

enough-analyst-54434

03/07/2023, 8:25 PM
Thus is frustrating. Yes, thats 1 time in a 6 week cycle. We could GH action the sync and remove that from the release process for cheap IIUC.
a

ancient-vegetable-10556

03/07/2023, 8:26 PM
Well, it’s one time, and we can’t enable the CI until the branch is cut
e

enough-analyst-54434

03/07/2023, 8:26 PM
I give up. Someone else interested in fixing the current release process missing doc updates will need to step in. Maybe this is just me,
a

ancient-vegetable-10556

03/07/2023, 8:28 PM
(Yes, it should be better, it’s not just you)
e

enough-analyst-54434

03/07/2023, 8:31 PM
So, staying very focused and simple. Is it ok to run that sync step listed in docs/README and, as such, can I add that to the release instructions?
h

happy-kitchen-89482

03/07/2023, 8:31 PM
Yeah I think the big error here was not updating the release instructions, and yes, it is always safe to run that sync step
a

ancient-vegetable-10556

03/07/2023, 8:31 PM
It is OK to ask Benjy, Chris, or Eric to run that step
e

enough-analyst-54434

03/07/2023, 8:31 PM
Excellent
h

happy-kitchen-89482

03/07/2023, 8:31 PM
From the appropriate release branch
a

ancient-vegetable-10556

03/07/2023, 8:31 PM
because we are the only people with API keys
e

enough-analyst-54434

03/07/2023, 8:31 PM
I can run it too!
a

ancient-vegetable-10556

03/07/2023, 8:31 PM
oh great!
even better
e

enough-analyst-54434

03/07/2023, 8:31 PM
Just, we already have that caveat in the release instructions @ancient-vegetable-10556
a

ancient-vegetable-10556

03/07/2023, 8:31 PM
perfect
h

happy-kitchen-89482

03/07/2023, 8:32 PM
(e.g., update the 2.15 only from the 2.15.x branch etc)
a

ancient-vegetable-10556

03/07/2023, 8:32 PM
If I find some time, I think I can/should pantsify those steps, too
e

enough-analyst-54434

03/07/2023, 8:32 PM
Well, the 1 is. The other is GH actionable as Tom showed.
a

ancient-vegetable-10556

03/07/2023, 8:33 PM
save for creating the branch; and accepting that we could accidentally hose edit suggestions that come through
f

fast-nail-55400

03/07/2023, 8:33 PM
Well, it’s one time, and we can’t enable the CI until the branch is cut
Why not publish a
main
version of the docs then?
e

enough-analyst-54434

03/07/2023, 8:33 PM
Yes, but creating the branch is alreayd a called out steo in the release instructions.
and accepting that we could accidentally hose edit suggestions that come through
Isn't this already a problem with docs/REAMDE?
Its not a new problem is it?
a

ancient-vegetable-10556

03/07/2023, 8:35 PM
@fast-nail-55400 Because you have to assign it a semver number (a shortcoming of Readme), and you can only mark them as “beta”, not as “pre-release”, @happy-kitchen-89482 decided it would be poor form to have two “beta” versions in place. Not an issue with RTD/Sphinx
@enough-analyst-54434 Not a new problem, but easier to accidentally bump up against when automated.
e

enough-analyst-54434

03/07/2023, 8:37 PM
Ok. SO it feels like we have a simple step - fix release docs. A maybe easy but less simple step - add this to CI with GH action and user-edits in the web UI be damnded, And everybody agrees on Sphinx/RTD, no lobbying needed, just time and effort. Is that a fair summary?
a

ancient-vegetable-10556

03/07/2023, 8:45 PM
almost everyone, but yes.
e

enough-analyst-54434

03/07/2023, 8:47 PM
Ok, good. Thanks. https://github.com/pantsbuild/pants/pull/18440 for the simplest step / stopping the bleeding.
a

ancient-vegetable-10556

03/07/2023, 8:48 PM
👀
e

enough-analyst-54434

03/07/2023, 9:04 PM
Ok, great. I just used those instructions to fix 2.16.0a0 docs. Thanks @ancient-vegetable-10556 .
a

ancient-vegetable-10556

03/07/2023, 9:04 PM
Not a problem
e

enough-analyst-54434

03/07/2023, 9:05 PM
And 2.15.x is now synced too.
2.15.x had 3 pencils: ✏️ successfully updated 'docker' with contents from docs/markdown/Docker/docker.md ✏️ successfully updated 'python-distributions' with contents from docs/markdown/Python/python/python-distributions.md ✏️ successfully updated 'changelog' with contents from docs/markdown/Releases/changelog.md
And then clean back to 2.11 where this looks like it started.
a

ancient-vegetable-10556

03/07/2023, 9:09 PM
That’s about right
3 Views