Skip to content

splitted commandlet-and-url-updater.adoc into two seperated docs - #2503

Open
gkenstel wants to merge 1 commit into
devonfw:mainfrom
gkenstel:noIssue_edit_commandlet_doc
Open

gkenstel wants to merge 1 commit into
devonfw:mainfrom
gkenstel:noIssue_edit_commandlet_doc

Conversation

@gkenstel

Copy link
Copy Markdown

This PR fixes TodoIssueID

Implemented changes:

  • Change 1

splitted documentation of commandlets and urlupdaters into seperated files.

Checklist for this PR

Make sure everything is checked before merging this PR. For further info please also see
our DoD.

  • When running mvn clean test locally all tests pass and build is successful
  • PR title is of the form #«issue-id»: «brief summary» (e.g. #921: fixed setup.bat and not feature/921 fixed setup.bat). If no issue ID exists, title only.
  • PR top-level comment summaries what has been done and contains link to addressed issue(s)
  • PR and issue(s) have suitable labels
  • Issue is set to In Progress and assigned to you or there is no issue (might happen for very small PRs)
  • You followed all coding conventions
  • You have added the issue implemented by your PR in CHANGELOG.adoc unless issue is labelled
    with internal
  • You have not changed any dependency in pom.xml files or otherwise if runtime dependencies changed, you have updated our LICENSE.asciidoc
  • You have formulated clear instructions on how to test your contribution under "Testing instructions"

Checklist for tool commandlets

Have you added a new «tool» as commandlet? There are the following additional checks:

  • The tool can be installed automatically (during setup via settings) or via the commandlet call
  • The tool is isolated in its IDEasy project, see Sandbox Principle
  • The new tool is added to the table of tools in LICENSE.asciidoc
  • The new commandlet is a command-wrapper for «tool»
  • Proper help texts for all supported languages are added here
  • The new commandlet installs potential dependencies automatically
  • The variables «TOOL»_VERSION and «TOOL»_EDITION are honored by your commandlet
  • The new commandlet is tested on all platforms it is available for or tested on all platforms that are in scope of the linked issue

@coveralls

Copy link
Copy Markdown
Collaborator

Coverage Report for CI Build 35327547649

Coverage increased (+0.02%) to 74.176%

Details

  • Coverage increased (+0.02%) from the base build.
  • Patch coverage: No coverable lines changed in this PR.
  • 1 coverage regression across 1 file.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

1 previously-covered line in 1 file lost coverage.

File Lines Losing Coverage Coverage
com/devonfw/tools/ide/version/VersionSegment.java 1 91.86%

Coverage Stats

Coverage Status
Relevant Lines: 19001
Covered Lines: 14726
Line Coverage: 77.5%
Relevant Branches: 8516
Covered Branches: 5685
Branch Coverage: 66.76%
Branches in Coverage %: Yes
Coverage Strength: 3.31 hits per line

💛 - Coveralls

@JoelAdbu JoelAdbu self-assigned this Sep 23, 2026

@JoelAdbu JoelAdbu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thank you @gkenstel for separating these two documentations. I know this is outside the scope of your PR, but since we are already updating the documentation, I think it would make sense to include these two small improvements as well.

Comment on lines 123 to 130
To test the UrlUpdater, you can run in addition to the unit test the `UpdateInitiator` class located in `url-updater/src/main/java/com/devonfw/tools/ide/url/updater/UpdateInitiator.java` which allows you to run the updater and see the discovered versions and URLs in the console.
The arguments to pass are:

* Path to ide-urls project (where the url-updater module is located)
* Time to wait for the updater to finish (e.g., PT1H)
* Name of the updater to run (e.g., mytool)

Once a day, the `UpdateInitiator` will run the updaters through GitHub Actions and fill the https://github.com/devonfw/ide-urls[ide-URL] repository with new version/tools that are identified by the Updaters.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We should update this section as well. There is actually one additional step required: UpdateInitiator expects a fourth argument, namely the path to the ide-urls-status repository, which is passed as the second argument.

Suggested change
Once a day, the `UpdateInitiator` will run the updaters through GitHub Actions and fill the https://github.com/devonfw/ide-urls[ide-URL] repository with new version/tools that are identified by the Updaters.
To test the UrlUpdater, you can run in addition to the unit test the `UpdateInitiator` class located in `url-updater/src/main/java/com/devonfw/tools/ide/url/updater/UpdateInitiator.java` which allows you to run the updater and see the discovered versions and URLs in the console.
Before running the updater, make sure the `ide-urls-status` repository is available under `project/_ide`. If it does not exist yet, clone it first.
The arguments to pass are:
* Path to ide-urls project (where the url-updater module is located)
* Path to ide-urls-status project
@@ -203,21 +128,3 @@
* Name of the updater to run (e.g., mytool)
Once a day, the `UpdateInitiator` will run the updaters through GitHub Actions and fill the https://github.com/devonfw/ide-urls[ide-URL] repository with new version/tools that are identified by the Updaters.

For an example of the required files, you can check the tests of other commandlets with the same base class).
* Proper help texts for all supported languages are added in `cli/src/main/resources/nls/` (`Help.properties`, `Help_de.properties`).
* The new tool is added to the table of tools in LICENSE.asciidoc with the correct license information and tags.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This might be useful to add. Quite often, developers implement the UrlUpdater and immediately start working on the corresponding Commandlet before the UrlUpdater itself has been merged.

In that situation, being able to test the Commandlet locally is very helpful, so I think adding this note would make sense.

Suggested change
=== Test a Commandlet locally (before the UrlUpdater is merged)
You can test a new Commandlet locally even if the corresponding UrlUpdater has not yet been merged.
 
Create a branch containing both your Commandlet changes and the UrlUpdater changes. Then follow the steps described in `url-updater.adoc` to run the `UpdateInitiator`.
 
1. Ensure that `ide-urls-status` is cloned under `projects/_ide`.
2. Create and checkout a dedicated branch in `urls`.
3. Run the `UpdateInitiator` as described in `url-updater.adoc`.
4. Commit the generated changes in `urls`.
5. Run `ide install <tool>` or `ide new <tool>` to test the Commandlet.
 
>[!Important]
Commit the generated changes before running ide install <tool> or ide new <tool>. Otherwise, the generated content may be discarded, and the Commandlet cannot be tested locally.

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

Labels

None yet

Projects

Status: Team Review

Development

Successfully merging this pull request may close these issues.

3 participants