-
Notifications
You must be signed in to change notification settings - Fork 1.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add missing frontmatter to some docs #3958
Add missing frontmatter to some docs #3958
Conversation
Hi @eliasnorrby. Thanks for your PR. I'm waiting for a tektoncd member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
/kind documentation |
/ok-to-test |
/test check-pr-has-kind-label |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you! A small update please
docs/install.md
Outdated
<!-- | ||
--- | ||
linkTitle: "Installation" | ||
weight: 1 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"1" is already used by tasks.md
- so maybe we can change that two 2?
There are already some details on the install process in https://tekton.dev/docs/getting-started/#installation - those are in the website repo though... so maybe we could add a link in there to this document too?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm glad you noticed! At first, I used 1
for install.md
and bumped all the other weights. But the thing is, there are multiple documents with with 2
already. Seeing this, I took the lazy approach of using 1
for both tasks.md
and install.md
, figuring they would be sorted alphabetically (as seems to be the case for the 2
s). But I can just as well take another pass and make sure weights are unique.
Then again, it's a weight
and not an order
property. Both docs relating to contracts have weight: 8
, which makes sense: they don't need to be in a specific order (I guess), but they should be grouped together. The problem is we're using too narrow a range, so it's hard to insert something between items.
Taking a closer look at the order as is now, it's a bit weird. I feel it would be more natural to have
- Install
- Task
- TaskRun
- Pipeline
- PipelineRun
as the components are ordered on the index page, not
- Install
- Task
- Events
- Runs < -- experimental feature
- TaskRuns
- Pipeline
- PipelineRun
as it is now.
Really going down the rabbit hole with this one, sorry. 😅
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As to the getting-started page: sure! Something like:
For more detailed installation instructions, see Installation.
added to the bottom of the Installation section?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here's a stab at a new set of weights. I tried ordering core components at the top, but I'm no Tekton expert yet, so let me know if something seems out of place.
install.md weight: 1
tasks.md weight: 2
taskruns.md weight: 3
pipelines.md weight: 4
pipelineruns.md weight: 5
resources.md weight: 6
workspaces.md weight: 7
events.md weight: 8
runs.md weight: 9
auth.md weight: 10
container-contract.md weight: 11
tekton-bundle-contracts.md weight: 12
logs.md weight: 13
labels.md weight: 14
conditions.md weight: 15
podtemplates.md weight: 16
enabling-ha.md weight: 17
metrics.md weight: 18
variables.md weight: 19
tekton-controller-performance-configuration.md weight: 20
migrating-from-knative-build.md weight: 40
migrating-v1alpha1-to-v1beta1.md weight: 40
deprecations.md weight: 50
I'm bumping the weight values for deprecations and migration guides (so they will stay at the bottom should any new docs be added in the future).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What do you think about this suggestion @afrittoli? I suppose pushing an update will require new test runs, so.. should I go ahead with this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@tektoncd/core-maintainers
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest pushing resources.md
down to the 15-20 range and pulling variables.md
up to the 10-15 range since PipelineResources are deprecated and variables are used everywhere. WDYT @afrittoli ?
Also: it might make future updates easier if the weights are wider apart (e.g. 100, 200, ..., 1000, 1100)? We wouldn't need to re-shuffle when a new addition is made between two existing entries, it could just use the mid-weight between two existing documents (e.g. 100
, 150
(new), 200
).
But I don't feel strongly about either of these - lgtm otherwise, cheers!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good idea! Pushed a new commit applying you suggestions.
New weights
install.md weight: 100
tasks.md weight: 200
taskruns.md weight: 300
pipelines.md weight: 400
pipelineruns.md weight: 500
workspaces.md weight: 600
events.md weight: 700
runs.md weight: 800
variables.md weight: 900 // higher up
auth.md weight: 1000
logs.md weight: 1100 // logs and metrics together
metrics.md weight: 1200
labels.md weight: 1300
podtemplates.md weight: 1400
enabling-ha.md weight: 1500
tekton-controller-performance-configuration.md weight: 1600
container-contract.md weight: 1700 // contracts shifted downward
tekton-bundle-contracts.md weight: 1800
resources.md weight: 2000 // deprecated, further down
conditions.md weight: 2100 // deprecated, further down
migrating-v1alpha1-to-v1beta1.md weight: 4000
migrating-from-knative-build.md weight: 4100
deprecations.md weight: 5000
/test pull-tekton-pipeline-alpha-integration-tests |
1 similar comment
/test pull-tekton-pipeline-alpha-integration-tests |
e67d780
to
6de7d0c
Compare
Some documentation files had no frontmatter block, making them invisible in the sidebar navigation on the website (since they were missing the linkTitle property). Fixed by adding the frontmatter block. Additionally, update weights to adjust the order of links: - Installation at the top - Deprecations at the bottom - Migration guides just before Deprecations Increase weight values to facilitate insertion of future documents.
6de7d0c
to
780f659
Compare
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: sbwsg The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks a lot @eliasnorrby for this, it's really helpful.
The new order looks good to me. Let merge this and see how it looks on the website :)
Would you be up for backporting to the past few releases?
/lgtm
/retest |
@afrittoli Yeah, sure! I wrote this little helper script for backporting a PRs changes to previous releases. I'll be running it against the release branches that are available and will let you know in tektoncd/website#271 if I'm missing any! |
See tektoncd/website#271 for more background.
Changes
Some documentation files had no frontmatter block, making them invisible
in the sidebar navigation on the website (since they were missing the
linkTitle property).
Update weights to adjust the order of links:
When finalized, these changes will have to be merged into the release branches of previous releases in order to keep the documentation layout consistent (again, see tektoncd/website#271).
Submitter Checklist
As the author of this PR, please check off the items in this checklist:
functionality, content, code)
Release Notes