diff --git a/content/doc/developer/publishing/wiki-page.adoc b/content/doc/developer/publishing/wiki-page.adoc index 39bac0cff6c7..dd2b53ce58a5 100644 --- a/content/doc/developer/publishing/wiki-page.adoc +++ b/content/doc/developer/publishing/wiki-page.adoc @@ -24,36 +24,42 @@ NOTE: If there is no ticket for the documentation migration created by the curre make sure to create one and then discuss with the plugin maintainers. Similarly, Asciidoc/Markdown preferences should be also discussed with maintainers. -There are the following migration steps: +The following list provides the migration steps: -. Search for the plugin to update in the link:https://reports.jenkins.io/jenkins-plugin-migration.html[plugin migration progress report] -** If the status of the plugin is _TODO_ then move on to step 2, else retry step one with a different plugin. +. Search for the plugin to update in the link:https://reports.jenkins.io/jenkins-plugin-migration.html[plugin migration progress report]. +** If the status of the plugin is _TODO_ move on to step two, else retry step one with a different plugin. . Fork the plugin repository in GitHub and clone it to your local machine. -. Search for and open the plugin page in the link:https://github.com/jenkins-infra/plugins-wiki-docs/[plugins-wiki-docs] repository -. Copy the README.md file and all docs/images to the plugin repository +. Search for and open the plugin page in the link:https://github.com/jenkins-infra/plugins-wiki-docs/[plugins-wiki-docs] repository. +. Copy the README.md file and all docs/images to the plugin repository. ** You can merge the copied file with the existing README file or create a new one. -. Copy-edit the documentation, see below +. Copy-edit the documentation as described <>. . Modify the URL documentation page reference in the project file so that it points to GitHub (link:/doc/developer/publishing/documentation/#referencing-the-documentation-page-from-the-project-file[documentation]). -. Commit changes, push them to your fork and create a pull request against the repository. +. Commit changes, push them to your fork, and create a pull request against the repository. +. Configure a redirect from the out-of-date wiki page to the migrated content. +NOTE: After migration, the continued existence of out-of-date wiki pages causes several problems, such as duplication, confusion, and unclear migration progress. +This persistence makes it harder to identify which pages have migrated and those waiting for migration. +If you cannot identify migrated pages, this creates a major technical obstacle in content migration from the wiki. + +[[copy-edit-documentation]] === Reviewing the documentation -. Review/edit the migrated file formatting +. Review/edit the migrated file formatting. ** If the document includes "Table of contents", remove this section in Markdown - or replace it by `:toc:` macros in Asciidoc (link:https://raw.githubusercontent.com/jenkinsci/.github/master/.github/release-drafter.adoc[example]). + or replace it using the `:toc:` macros in Asciidoc (link:https://raw.githubusercontent.com/jenkinsci/.github/master/.github/release-drafter.adoc[example]). ** If the source Wiki page includes code blocks, they will need to be manually converted. Pandoc exports them as tables. -. Extract changelogs to a separate file +. Extract changelogs to a separate file. ** It is recommended to extract changelogs to a separate `CHANGELOG.md` file in the repository root. - It allows tools like Dependabot to read changelog summaries + It allows tools like Dependabot to read changelog summaries. ** Use versions as headers. Changelogs in Wiki often include release dates, but it is better to keep them in the text below the header. ** Examples: link:https://github.com/jenkinsci/envinject-api-plugin/blob/master/CHANGELOG.md[EnvInject API Plugin], link:https://github.com/jenkinsci/aws-java-sdk-plugin/blob/master/CHANGELOG.md[AWS Java SDK Plugin] -. Review the text -** Verify formatting and spelling +. Review the text. +** Verify formatting and spelling. ** Wiki pages are often outdated, and it is nice to review them before submitting - (e.g. rename "slave" to "agent", "workflow" to "pipeline", "Hudson" to "Jenkins", etc.) -. Check that the images are not outdated -** A lot of UI changes have occurred, and wiki pages often contain out-of-date images (images that contain keywords like Hudson will need to be replaced) -. Commit changes, push them to your fork and create a pull request against the plugin repository -. Once the pull request is merged, create an `INFRA` Jenkins JIRA ticket to replace the content on Wiki by a link to the new jenkins.io locations + (e.g. rename "slave" to "agent", "workflow" to "pipeline", "Hudson" to "Jenkins", etc.). +. Check that the images are not outdated. +** A lot of UI changes have occurred, and wiki pages often contain out-of-date images (images that contain keywords like Hudson will need to be replaced). +. Commit changes, push them to your fork and create a pull request against the plugin repository. +. Once the pull request is merged, create an `INFRA` Jenkins JIRA ticket to replace the content on Wiki by a link to the new jenkins.io locations.