From a88046204e23f94139fb4ed2d99c32ca36bcee16 Mon Sep 17 00:00:00 2001 From: pyther-hub Date: Wed, 27 Mar 2024 00:18:31 +0530 Subject: [PATCH 01/12] Added a section of Update parent POM page --- .../tutorial-improve/update-parent-pom.adoc | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/content/doc/developer/tutorial-improve/update-parent-pom.adoc b/content/doc/developer/tutorial-improve/update-parent-pom.adoc index 936c3fc89e87..36ee38fd75b0 100644 --- a/content/doc/developer/tutorial-improve/update-parent-pom.adoc +++ b/content/doc/developer/tutorial-improve/update-parent-pom.adoc @@ -19,6 +19,52 @@ The most recent parent POM files also provide additional static analysis like sp // Create the branch include::doc/developer/tutorial-improve/_create-a-branch.adoc[] + +== Maven configuration + +Before updating the parent POM (Project Object Model) using the "mvn -ntp version:update-parent" command, you must make sure that the Maven configuration files are correctly configured. +This is important because the plugin:maven-hpi-plugin[maven-hpi-plugin], used for developing Jenkins plugins, might require some additional global configurations to function correctly with older plugin environments. + +If Maven reports that it cannot download artifacts during the update process, it might be due to improper configuration settings. +To address this issue, create a file named `settings.xml` in the `/m2` directory, which is the default location for Maven settings, and configure it with the following content: + + + + +[source,bash] +---- + + + org.jenkins-ci.tools + + + + jenkins + + true + + + + repo.jenkins-ci.org + https://repo.jenkins-ci.org/public/ + + + + + repo.jenkins-ci.org + https://repo.jenkins-ci.org/public/ + + + + + +---- + + + == Compile the plugin Use Apache Maven to compile the plugin. From bf3688d9a4b6a27ec80da9e43b55ce832a10c2a8 Mon Sep 17 00:00:00 2001 From: pyther-hub Date: Thu, 28 Mar 2024 17:29:41 +0530 Subject: [PATCH 02/12] minor wording changed --- .../developer/tutorial-improve/update-parent-pom.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/doc/developer/tutorial-improve/update-parent-pom.adoc b/content/doc/developer/tutorial-improve/update-parent-pom.adoc index 36ee38fd75b0..b0c9e88635f9 100644 --- a/content/doc/developer/tutorial-improve/update-parent-pom.adoc +++ b/content/doc/developer/tutorial-improve/update-parent-pom.adoc @@ -22,16 +22,16 @@ include::doc/developer/tutorial-improve/_create-a-branch.adoc[] == Maven configuration -Before updating the parent POM (Project Object Model) using the "mvn -ntp version:update-parent" command, you must make sure that the Maven configuration files are correctly configured. -This is important because the plugin:maven-hpi-plugin[maven-hpi-plugin], used for developing Jenkins plugins, might require some additional global configurations to function correctly with older plugin environments. +Before you proceed with the parent POM update, you must make sure that Maven is installed on your machine and that it is configured correctly for Jenkins plugin development. +This is important because the link:https://github.com/jenkinsci/maven-hpi-plugin[maven-hpi-plugin], used for developing Jenkins plugins, requires some additional global configurations to function correctly with older plugin environments. -If Maven reports that it cannot download artifacts during the update process, it might be due to improper configuration settings. -To address this issue, create a file named `settings.xml` in the `/m2` directory, which is the default location for Maven settings, and configure it with the following content: +Improper configuration settings can cause Maven to report that it cannot download artifacts during the update process. +To address this issue, create a file named `settings.xml` in the `~/.m2` directory, which is the default location for Maven settings, and configure it with the following content: -[source,bash] +[source,xml] ---- Date: Thu, 28 Mar 2024 19:25:05 +0530 Subject: [PATCH 03/12] added on how to use checkUrl in Form validation --- content/doc/developer/forms/form-validation.adoc | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/doc/developer/forms/form-validation.adoc b/content/doc/developer/forms/form-validation.adoc index 554e7ecc4036..3ea041790670 100644 --- a/content/doc/developer/forms/form-validation.adoc +++ b/content/doc/developer/forms/form-validation.adoc @@ -45,6 +45,14 @@ public FormValidation doCheckThreads(@QueryParameter("value") final String meani This naming convention is how Jenkins wires up your form validation method. The return type also must be FormValidation, which offers various static factory methods to create an instance. Form validation can be of 3 different kinds: `ok`, `warning` or `error`. Validation message can either be represented in plaintext or use HTML markup. Several validations of different kinds can be reported wrapping then into one using aggregate factory method. +=== To set up form validation within a Jelly template + +To configure form validation within a Jelly template to call doCheckXxx methods defined in a particular class in Jenkins, you'll indeed utilize the checkUrl and checkDependsOn attributes. Here's a breakdown of how these attributes are used: + +The checkUrl Attribute specifies the URL that Jenkins will request to perform form validation. Typically, this URL points to the Jenkins server, where it handles the validation request. The value entered in the input field will be checked via AJAX against this URL, and any errors encountered will be rendered under the text field. This URL is associated with the method responsible for performing the validation (doCheckXxx method) within your Descriptor class. + +The checkDependsOn Attribute defines the dependency between the field being validated and the field(s) whose values are required for validation. It specifies the ID(s) of the field(s) that the validation depends on. When the dependent field(s) change, Jenkins triggers the validation of the current field. Additionally, the fields specified in checkDependsOn are sent along with the form validation request. + == Getting values of other fields Sometimes your validation method needs values of other input fields to perform a check. You do this by defining them as additional parameters: From 008b299bc1c0cc3708e8c41a5f4c53892e85a0d3 Mon Sep 17 00:00:00 2001 From: pyther-hub Date: Thu, 28 Mar 2024 23:40:03 +0530 Subject: [PATCH 04/12] removed extra part --- .../tutorial-improve/update-parent-pom.adoc | 46 ------------------- 1 file changed, 46 deletions(-) diff --git a/content/doc/developer/tutorial-improve/update-parent-pom.adoc b/content/doc/developer/tutorial-improve/update-parent-pom.adoc index b0c9e88635f9..936c3fc89e87 100644 --- a/content/doc/developer/tutorial-improve/update-parent-pom.adoc +++ b/content/doc/developer/tutorial-improve/update-parent-pom.adoc @@ -19,52 +19,6 @@ The most recent parent POM files also provide additional static analysis like sp // Create the branch include::doc/developer/tutorial-improve/_create-a-branch.adoc[] - -== Maven configuration - -Before you proceed with the parent POM update, you must make sure that Maven is installed on your machine and that it is configured correctly for Jenkins plugin development. -This is important because the link:https://github.com/jenkinsci/maven-hpi-plugin[maven-hpi-plugin], used for developing Jenkins plugins, requires some additional global configurations to function correctly with older plugin environments. - -Improper configuration settings can cause Maven to report that it cannot download artifacts during the update process. -To address this issue, create a file named `settings.xml` in the `~/.m2` directory, which is the default location for Maven settings, and configure it with the following content: - - - - -[source,xml] ----- - - - org.jenkins-ci.tools - - - - jenkins - - true - - - - repo.jenkins-ci.org - https://repo.jenkins-ci.org/public/ - - - - - repo.jenkins-ci.org - https://repo.jenkins-ci.org/public/ - - - - - ----- - - - == Compile the plugin Use Apache Maven to compile the plugin. From b03fcfd61c724ed7f9fa98eca1188f458ce7a010 Mon Sep 17 00:00:00 2001 From: pyther-hub Date: Fri, 29 Mar 2024 01:43:14 +0530 Subject: [PATCH 05/12] changes have been made to clarify that once a page has undergone migration, redirection from the old wiki page is necessary. --- content/doc/developer/publishing/wiki-page.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/doc/developer/publishing/wiki-page.adoc b/content/doc/developer/publishing/wiki-page.adoc index 39bac0cff6c7..649e1bca8070 100644 --- a/content/doc/developer/publishing/wiki-page.adoc +++ b/content/doc/developer/publishing/wiki-page.adoc @@ -36,6 +36,8 @@ There are the following migration steps: . 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. +Note:- There is a major technical obstacle in the way of content migration from the wiki. This difficulty stems from the requirement that, when the material has been properly moved, the out-of-date wiki page be removed and a redirection mechanism to the migrated version be set up. After migration, the continued existence of out-of-date wiki pages causes a number of problems, such as duplication, confusion, and unclear migration progress. This persistence not only makes the process more difficult overall, but it also makes it more difficult to identify which material has already been migrated and which is still waiting, which makes the work at hand much more difficult. + === Reviewing the documentation . Review/edit the migrated file formatting From 03b812a83eb5a2e70b969b034a9dd491d6164e01 Mon Sep 17 00:00:00 2001 From: pyther-hub Date: Fri, 29 Mar 2024 03:48:18 +0530 Subject: [PATCH 06/12] removed unwanted part --- content/doc/developer/forms/form-validation.adoc | 7 ------- 1 file changed, 7 deletions(-) diff --git a/content/doc/developer/forms/form-validation.adoc b/content/doc/developer/forms/form-validation.adoc index 3ea041790670..4efe651bc48b 100644 --- a/content/doc/developer/forms/form-validation.adoc +++ b/content/doc/developer/forms/form-validation.adoc @@ -45,13 +45,6 @@ public FormValidation doCheckThreads(@QueryParameter("value") final String meani This naming convention is how Jenkins wires up your form validation method. The return type also must be FormValidation, which offers various static factory methods to create an instance. Form validation can be of 3 different kinds: `ok`, `warning` or `error`. Validation message can either be represented in plaintext or use HTML markup. Several validations of different kinds can be reported wrapping then into one using aggregate factory method. -=== To set up form validation within a Jelly template - -To configure form validation within a Jelly template to call doCheckXxx methods defined in a particular class in Jenkins, you'll indeed utilize the checkUrl and checkDependsOn attributes. Here's a breakdown of how these attributes are used: - -The checkUrl Attribute specifies the URL that Jenkins will request to perform form validation. Typically, this URL points to the Jenkins server, where it handles the validation request. The value entered in the input field will be checked via AJAX against this URL, and any errors encountered will be rendered under the text field. This URL is associated with the method responsible for performing the validation (doCheckXxx method) within your Descriptor class. - -The checkDependsOn Attribute defines the dependency between the field being validated and the field(s) whose values are required for validation. It specifies the ID(s) of the field(s) that the validation depends on. When the dependent field(s) change, Jenkins triggers the validation of the current field. Additionally, the fields specified in checkDependsOn are sent along with the form validation request. == Getting values of other fields Sometimes your validation method needs values of other input fields to perform a check. You do this by defining them as additional parameters: From f92296a8bc3bee6277f87717bf103aa2b8ad55db Mon Sep 17 00:00:00 2001 From: pyther-hub Date: Sun, 31 Mar 2024 01:11:41 +0530 Subject: [PATCH 07/12] minor changes --- content/doc/developer/forms/form-validation.adoc | 1 - content/doc/developer/publishing/wiki-page.adoc | 5 ++++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/content/doc/developer/forms/form-validation.adoc b/content/doc/developer/forms/form-validation.adoc index 4efe651bc48b..554e7ecc4036 100644 --- a/content/doc/developer/forms/form-validation.adoc +++ b/content/doc/developer/forms/form-validation.adoc @@ -45,7 +45,6 @@ public FormValidation doCheckThreads(@QueryParameter("value") final String meani This naming convention is how Jenkins wires up your form validation method. The return type also must be FormValidation, which offers various static factory methods to create an instance. Form validation can be of 3 different kinds: `ok`, `warning` or `error`. Validation message can either be represented in plaintext or use HTML markup. Several validations of different kinds can be reported wrapping then into one using aggregate factory method. - == Getting values of other fields Sometimes your validation method needs values of other input fields to perform a check. You do this by defining them as additional parameters: diff --git a/content/doc/developer/publishing/wiki-page.adoc b/content/doc/developer/publishing/wiki-page.adoc index 649e1bca8070..2376f8d192bd 100644 --- a/content/doc/developer/publishing/wiki-page.adoc +++ b/content/doc/developer/publishing/wiki-page.adoc @@ -36,7 +36,10 @@ There are the following migration steps: . 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. -Note:- There is a major technical obstacle in the way of content migration from the wiki. This difficulty stems from the requirement that, when the material has been properly moved, the out-of-date wiki page be removed and a redirection mechanism to the migrated version be set up. After migration, the continued existence of out-of-date wiki pages causes a number of problems, such as duplication, confusion, and unclear migration progress. This persistence not only makes the process more difficult overall, but it also makes it more difficult to identify which material has already been migrated and which is still waiting, which makes the work at hand much more difficult. +NOTE: After migration, the continued existence of out-of-date wiki pages causes a number of problems, such as duplication, confusion, and unclear migration progress. +This persistence not only makes the process more difficult overall, but it also makes it harder to identify which pages have already been migrated and which are still waiting. +This is a major technical obstacle in the way of content migration from the wiki. +When migrating documentation, after the material has been properly moved, the out-of-date wiki page must be removed and a redirect must be configured to the migrated version. === Reviewing the documentation From 03d4b326e1edd73d9a734a9e11b9aa11b4bf1bed Mon Sep 17 00:00:00 2001 From: Kevin Martens <99040580+kmartens27@users.noreply.github.com> Date: Mon, 8 Apr 2024 12:48:53 -0400 Subject: [PATCH 08/12] Update content/doc/developer/publishing/wiki-page.adoc --- content/doc/developer/publishing/wiki-page.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/doc/developer/publishing/wiki-page.adoc b/content/doc/developer/publishing/wiki-page.adoc index 2376f8d192bd..ce0307e7caf8 100644 --- a/content/doc/developer/publishing/wiki-page.adoc +++ b/content/doc/developer/publishing/wiki-page.adoc @@ -36,10 +36,10 @@ There are the following migration steps: . 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. -NOTE: After migration, the continued existence of out-of-date wiki pages causes a number of problems, such as duplication, confusion, and unclear migration progress. -This persistence not only makes the process more difficult overall, but it also makes it harder to identify which pages have already been migrated and which are still waiting. -This is a major technical obstacle in the way of content migration from the wiki. -When migrating documentation, after the material has been properly moved, the out-of-date wiki page must be removed and a redirect must be configured to the migrated version. +NOTE: After migration, the continued existence of out-of-date wiki pages can cause several problems, such as duplication, confusion, and unclear migration progress. +This persistence makes the process more difficult overall and makes it harder to identify which pages have already migrated and those still waiting for migration. +This is a major technical obstacle for content migration from the wiki. +When migrating documentation, after the material has been properly moved, you must remove the out-of-date wiki page and configure a redirect to the migrated version. === Reviewing the documentation From f839cd28a6d6dd0a89bafaf0469c0ec7d42db021 Mon Sep 17 00:00:00 2001 From: pyther-hub Date: Tue, 9 Apr 2024 16:28:53 +0530 Subject: [PATCH 09/12] rephrased --- content/doc/developer/publishing/wiki-page.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/doc/developer/publishing/wiki-page.adoc b/content/doc/developer/publishing/wiki-page.adoc index 2376f8d192bd..a3112377da16 100644 --- a/content/doc/developer/publishing/wiki-page.adoc +++ b/content/doc/developer/publishing/wiki-page.adoc @@ -36,10 +36,10 @@ There are the following migration steps: . 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. -NOTE: After migration, the continued existence of out-of-date wiki pages causes a number of problems, such as duplication, confusion, and unclear migration progress. -This persistence not only makes the process more difficult overall, but it also makes it harder to identify which pages have already been migrated and which are still waiting. -This is a major technical obstacle in the way of content migration from the wiki. -When migrating documentation, after the material has been properly moved, the out-of-date wiki page must be removed and a redirect must be configured to the migrated version. +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. +When migrating documentation, the out-of-date wiki page must be removed and have a redirect configured to point to the migrated version. === Reviewing the documentation From c02ba7357f05e7d3ebe1e6b25bb661be17aa3584 Mon Sep 17 00:00:00 2001 From: Kevin Martens <99040580+kmartens27@users.noreply.github.com> Date: Fri, 12 Apr 2024 13:31:37 -0400 Subject: [PATCH 10/12] Update content/doc/developer/publishing/wiki-page.adoc Co-authored-by: Mark Waite --- content/doc/developer/publishing/wiki-page.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/developer/publishing/wiki-page.adoc b/content/doc/developer/publishing/wiki-page.adoc index a3112377da16..be528819a10c 100644 --- a/content/doc/developer/publishing/wiki-page.adoc +++ b/content/doc/developer/publishing/wiki-page.adoc @@ -39,7 +39,7 @@ There are the following migration steps: 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. -When migrating documentation, the out-of-date wiki page must be removed and have a redirect configured to point to the migrated version. +When migrating documentation, the out-of-date wiki page must have a redirect configured to point to the migrated version. === Reviewing the documentation From 95264e91cd8a58ed427c09c8b8bd3a90443d1196 Mon Sep 17 00:00:00 2001 From: Kevin Martens <99040580+kmartens27@users.noreply.github.com> Date: Tue, 16 Apr 2024 14:22:29 -0400 Subject: [PATCH 11/12] add redirect configuration to steps --- content/doc/developer/publishing/wiki-page.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/developer/publishing/wiki-page.adoc b/content/doc/developer/publishing/wiki-page.adoc index be528819a10c..76932a69b49f 100644 --- a/content/doc/developer/publishing/wiki-page.adoc +++ b/content/doc/developer/publishing/wiki-page.adoc @@ -35,11 +35,11 @@ There are the following migration steps: . Copy-edit the documentation, see 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. +. 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. -When migrating documentation, the out-of-date wiki page must have a redirect configured to point to the migrated version. === Reviewing the documentation From b132821db272f1219101cc68df8a3183a668d4d6 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Wed, 17 Apr 2024 21:41:56 -0600 Subject: [PATCH 12/12] Improve link to table of contents example --- content/doc/developer/publishing/wiki-page.adoc | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/content/doc/developer/publishing/wiki-page.adoc b/content/doc/developer/publishing/wiki-page.adoc index 28c8dc317631..dc6fa7f72a94 100644 --- a/content/doc/developer/publishing/wiki-page.adoc +++ b/content/doc/developer/publishing/wiki-page.adoc @@ -41,20 +41,16 @@ NOTE: After migration, the continued existence of out-of-date wiki pages causes 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. -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. ** If the document includes "Table of contents", remove this section in Markdown - or replace it using the `: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://github.com/jenkinsci/.github/blob/master/.github/release-drafter.adoc?plain=1[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. -** It is recommended to extract changelogs to a separate `CHANGELOG.md` file in the repository root. +. Extract changelogs to a separate file or create GitHub releases for past versions. +** If you create a changelog file, extract the changelogs to a separate `CHANGELOG.md` file in the repository root. 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.