Closed gunnar-solo closed 1 year ago
One aspect that we haven't discussed with this work: https://github.com/solo-io/gloo/blob/master/docs/content/static/content/version_gee_n%2B1.md is a manually maintained file. Can we automate this somehow so the docs team doesn't have to push changes with these values? How beneficial would this be @Nadine2016?
adding some closing context to this issue:
There are a couple of asks to the issue that were not addressed at the time of closing. Namely:
Gloo Mesh
already has a useful, working solution that can be copied, if desired"N+1"
or similar such things. The ask is to auto-update these files, either on release or on docs publishultimately, these weren't addressed at the time of issue closing as the "main intent" of this issue has been accomplished. A.K.A.: "make docs easier/faster to publish". Context was added, here, in the event that we would like to re-up this issue or related work in the future.
Spoke with @Nadine2016 and @nfuden
The plan to migrate docs maintenance out of this repo is delayed. As a result, it would help the docs team a lot to have tests not run on docs changes:
add the ability to skip CI -- the idea was that we could add a comment directive/github tag/changelog directive to stop CI from taking place, thus enabling faster merges on PRs which didn't warrant such scrutiny. Ex: spelling change/broken link. Gloo Mesh already has a [useful, working solution](https://github.com/solo-io/gloo-mesh-enterprise/blob/main/.github/workflows/add-skipci-label.yaml) that can be copied, if desired
Reopening.
New definition of done, is having an ability to skip tests on a docs PR. Clearly outlined and docs team familiar with how to use it and has verified it.
The ability to skip CI for docs PRs was introduced with https://github.com/solo-io/gloo/pull/8307
What already exists
At present,
gloo
has a rather complicated/nested build processes in place to publish docs:master
gloo
versions) a. docs-gen.yaml b. make build-site c. build-docs.sh d. make site-releaseWhat's the problem?
This process leaves a lot to be desired. Notably, it...
active_versions.json
)How do we make it better?
So! There is room for several quick wins/improvements. This issue is explicitly to do them. From a meeting with @gunnar-solo, @sam-heilbron, and @Nadine2016, it was discussed to...
active_vesrions.json
not depend onMajor.Minor.Patch
but insteadMajor.Minor.x
. Confirm that releases workWhy not revamp the entire system?
This was briefly touched on, then rejected. Ultimately, docs are being lifted to a single, centralized place across the
solo
org. A.K.A.: anything done, here, is meant to be a stopgap solution to make life "nicer" in the pre-lift times (author's guess: the next 8 months)