Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Developer Documentation - update for wiki migration page #7255

Merged
merged 2 commits into from
Apr 18, 2024
Merged

Developer Documentation - update for wiki migration page #7255

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
69be9fe
docs update for wiki migration page
kmartens27 Apr 16, 2024
2936846
additional adjustment for grammar
kmartens27 Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 24 additions & 18 deletions content/doc/developer/publishing/wiki-page.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<copy-edit-documentation, below>>.
. 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.