https://pantsbuild.org/ logo
Join Slack
Powered by
can someone with API keys to <readme.com> update t...
# development
c
can someone with API keys to readme.com update the 2.16 docs from 
main
?
e
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
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
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
Any reason we cannot use it?
e
@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
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
https://github.com/pantsbuild/pants/issues/18437 is (in actuality) a proposal to do just that
e
And there are instructions under 
docs/
for how to sync the human-authored markdown in that dir.
Was this known by people generally?
a
@enough-analyst-54434 answering your question presently
e
I always assumed the releaser instructions were complete.
a
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
Ok, that's a big gap then. I had no idea.
a
(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
But the release process already says regen the reference /ask someone else. It should also say ditto for the docs/README step.
a
that’s definitely doable.
e
Yeah - this is a huge hole. Presumably no releasers save Benjy have been doing this at all this year?
a
right
e
K. Good to understand the mystery. Thanks.
a
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
It sounds like the investment is on the pennies level assuming Tom's GH action link works.
a
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
So, the current doc/README has caveats? We can't just blindly sync?
a
(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
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
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
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
Well, it’s one time, and we can’t enable the CI until the branch is cut
e
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
(Yes, it should be better, it’s not just you)
e
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
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
It is OK to ask Benjy, Chris, or Eric to run that step
e
Excellent
h
From the appropriate release branch
a
because we are the only people with API keys
e
I can run it too!
a
oh great!
even better
e
Just, we already have that caveat in the release instructions @ancient-vegetable-10556
a
perfect
h
(e.g., update the 2.15 only from the 2.15.x branch etc)
a
If I find some time, I think I can/should pantsify those steps, too
e
Well, the 1 is. The other is GH actionable as Tom showed.
a
save for creating the branch; and accepting that we could accidentally hose edit suggestions that come through
f
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
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
@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
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
almost everyone, but yes.
e
Ok, good. Thanks. https://github.com/pantsbuild/pants/pull/18440 for the simplest step / stopping the bleeding.
a
đź‘€
e
Ok, great. I just used those instructions to fix 2.16.0a0 docs. Thanks @ancient-vegetable-10556 .
a
Not a problem
e
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
That’s about right
3 Views
Open in Slack
PreviousNext
Powered by