Skip to content

docs: remove stale WIP markers from developer docs (#8134)#8885

Open
Flamki wants to merge 3 commits intojenkins-infra:masterfrom
Flamki:docs-cleanup-developer-wip-8134
Open

docs: remove stale WIP markers from developer docs (#8134)#8885
Flamki wants to merge 3 commits intojenkins-infra:masterfrom
Flamki:docs-cleanup-developer-wip-8134

Conversation

@Flamki
Copy link
Contributor

@Flamki Flamki commented Feb 23, 2026

Summary

Audit the developer documentation pages under /doc/developer/ and remove WIP markers from pages that already contain substantial content.

This reduces noisy WIP warnings/icons in the Developer Guide while keeping WIP markers on placeholder/stub pages.

Changes

Removed wip: true from:

  • content/doc/developer/architecture/index.adoc
  • content/doc/developer/architecture/extensions.adoc
  • content/doc/developer/FIPS-140/index.adoc
  • content/doc/developer/extensibility/index.adoc
  • content/doc/developer/handling-requests/actions.adoc
  • content/doc/developer/security/index.adoc
  • content/doc/developer/tutorial/index.adoc
  • content/doc/developer/views/index.adoc

Notes

WIP markers were intentionally kept on sparse pages that are still mostly placeholders (for example distributed-builds, model, scheduling, and parts of initialization and internationalization).

Deals with #8134

@Flamki Flamki requested review from a team as code owners February 23, 2026 15:59
@probot-autolabeler probot-autolabeler bot added the documentation Jenkins documentation, including user and developer docs, solution pages, etc. label Feb 23, 2026
@Flamki
Copy link
Contributor Author

Flamki commented Feb 24, 2026

Hi @gounthar👋
Friendly ping on this PR. All checks are passing.
Please let me know if any changes are needed. Happy to update. 🙏

@krisstern
Copy link
Member

Hi,
Please refrain from pinging anyone in the copy editing team to get reviews. We will review your PR shortly.

@krisstern
Copy link
Member

Hi,
I don't think this PR fixes #8134 completely, so I will update the ticket accordingly

@Flamki
Copy link
Contributor Author

Flamki commented Feb 24, 2026

Apologies for the ping — I’ll wait for the normal review process.
Thanks for updating #8134. Could you please clarify what’s still missing so I can address it?
Thank you.

@krisstern
Copy link
Member

krisstern commented Feb 24, 2026

The original ticket #8134 is supposed to be an auditing task and involves reporting back to us which WIP are no longer required and to remove all the unnecessary ones in the repo and not just a subset of this. Your PR does not seem to have addressed the scope of the ticket completely.

Copy link
Contributor

@daniel-beck daniel-beck left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I disagree with basically all of these.

Just because there's text on a page doesn't mean it's the text that's expected to be there. E.g., https://www.jenkins.io/doc/developer/handling-requests/actions/ only has content for a specific behavior change several years ago -- and nothing else.

@Flamki
Copy link
Contributor Author

Flamki commented Feb 25, 2026

Thanks for the feedback. I’ve updated this PR accordingly.

I restored wip: true on all previously changed pages except the two below, based on the point that content presence alone does not imply page completeness.

Current scope of this PR is now only:

  • content/doc/developer/FIPS-140/index.adoc
  • content/doc/developer/tutorial/index.adoc

Why these two were kept as removal candidates:

  • FIPS-140/index.adoc: focused, self-contained guidance page (front matter + complete topic content, no placeholder sections, no WIP/TODO blocks in body).
  • tutorial/index.adoc: navigation/entry page for a complete 4-step tutorial flow (prepare, create, run, extend), where each linked page has substantial content.

I also completed a full audit of wip: true markers under content/:

  • Total found: 21
  • Kept as WIP after audit: 19
  • Proposed for WIP removal in this PR: 2 (the files above)

If you want these two to remain WIP as well, I can revert them too and convert this into an audit-only update.

@krisstern
Copy link
Member

Hi thanks @Flamki for the follow-up!

But your report and thinking are just not detailed and thorough enough. To me the reality for tackling any issue would be either you put in the effort to complete the task to 100% or it would be better not to try in vain at all. This does no one any good to be honest, and it is a waste of maintainer time.

@Flamki
Copy link
Contributor Author

Flamki commented Mar 2, 2026

Thanks for the feedback. I completed a full file-by-file audit of all wip: true markers under content/ and posted it in #8134.

For this PR, I kept scope intentionally minimal and only left two removal candidates:

  • content/doc/developer/FIPS-140/index.adoc
  • content/doc/developer/tutorial/index.adoc

Everything else remains WIP per the full audit rationale.

If you prefer stricter handling, I can revert these two as well and keep this effort audit-only.
Could you confirm which direction you want?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Jenkins documentation, including user and developer docs, solution pages, etc.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants