Change:
<!-- If this is a BUG REPORT, please: Fill in as much of the template below as you can. If you leave out information, we can't help you as well. If this is a FEATURE REQUEST, please: Describe in detail the feature/behavior/change you'd like to see. In both cases, be ready for followup questions, and please respond in a timely manner. If we can't reproduce a bug or think a feature already exists, we might close your issue. If we're wrong, PLEASE feel free to reopen it and explain why. --Kubernetes version (use ): 1.6.1 What happened: I downloaded The files and others just contains the 'this is an autogenerated doc place holder` The markdown docs like in etc. also just contains the placeholder text. What you expected to happen: I'm expecting the release tarball to contain the generated manpages similar to the markdown ones in
Looks like this has been broken for a while - I just checked v.1.3.1, and it similarly contains the placeholder docs. Looks like caused it, and I guess we forgot to update to generate docs before release?
This should happen . Checking further.
Seems to be related to The doc generation does happen at branch time, but due to recently introduced issues with verify-all failing on the branch, update- has been run by the release managers which undoes the doc generation because it runs the update-generated- Once we sort out , this problem will resolve. Unfortunately for those releases already out, there's not obvious path for resolution. In the mean-time release-managers can run hack/generate- on the branch to fix docs for future releases on existing branches.
According to the comment above by the generated docs are no longer checked in. Doesn't that mean anago needs to generate them every time it runs?
Anago generates them at branch time on new branches .
Ah I see. I thought "no longer checked in" meant that the generated files are placed in an output directory that's ignored by git. But actually what it means is that we check in the stubs in-place on top of the real files. Is your plan that eventually we will stop running update- on the release branch? I thought that should be a normal part of the workflow for any PR - some parts are needed even for cherrypicks (e.g. update-bazel). It would be confusing if running update-all on a cherrypick produces a PR that wipes out all the docs. Also won't verify-generated-docs start to fail if the files are not stubs? Should we fix update/verify-generated-docs to detect when they're run on a branch that's supposed to have docs? Perhaps we could create and check in a hidden marker file upon branching off of master?
Alternatively, we could let the docs stay as stubs in the release branch, and have anago run generate- at release build time, rather than at branch cut time.
At one point the workflow precluded running update- on branches and/or update-generate- was not part of that. I haven't done the archaeology yet to determine how we got to this point recently, but created this split some time last year and it was to avoid the doc churn on master and generate the docs once at branch time.
FWIW we did the same switch in Openshift, and moved the generation during the RPM build.
IMO generating the docs at release build time makes the most sense, since things may change on a release branch over time as fixes get cherry-picked in.
As a general rule, yes, you want to generate the docs "at release time", but you also don't want to create churn or changes where none are needed. It could be that things have changed enough to where it's more appropriate now to run this with each release vs. at branch time, but what data do we have to back that up? What changes have landed on branches over the past few releases that required regenerating the docs that were generated at branch time?
Usually you shouldn't have diffs in release branches since new changes mean either additions; new features and we are not backporting features, it seems, or updates/deletions which are likely non-backwards compatible. are you suggesting to have the docs generated when a branch is cut and leave them off just master?
Also even if we generated them at branch time, cherry-picks would merely be required to update those generated changes which doesn't seem like a big deal? I can get behind that.
Right, the branches are the 'stabilized' bit here. If cherrypicks are coming from master that require update- changes, then all of those related commits should come over (from master) and land as a unit on the branch. At least that's the way it's been working til now since the great doc move/shift of last year when update-generated- got repurposed to generate stubs and generate- was introduced and .
I'm not sure exactly how docs are generated, but if we generate docs only at branch time, how will we know if a cherry-picked change affects docs, since the docs aren't checked into the master branch? e.g. Suppose we generate docs for release-1.7 when we cut the branch. Later, we cherry-pick some change to kubectl which would affect the manpages, but we also cherry-pick 5 other changes which don't. How will we know when to regenerate docs on release-1.7, and when will that happen? Do we regenerate docs every time we make a cherry-pick to the release branch, just in case?
This issue hasn't come up since we implemented the at-branch-time doc generation several months ago, but there is a good point made here. Now that we're considering this again, would it make more sense for the cherrypick process to generate any doc changes in order to couple them with a specific cherrypick and to have them reviewed as part of that change? The other alternative as suggested is to simply regenerate all docs (which may or may not be a no-op) with each release on a branch.
/sig release

Discussion:
done gitamcleanup=false <ins> # Re-generate docs (if needed) echo echo "Regenerating docs..." if ! hack/generate-docs.sh; then echo echo "hack/generate-docs.sh FAILED to complete." exit 1 fi </ins> if [[ -n "${DRY_RUN}" ]]; then echo "!!! Skipping git push and PR creation because you set DRY_RUN." echo "To return to the branch you were in when you invoked this script:"