Folder Computation documentation needs update

[kmartens27]

Describe your use-case which is not covered by existing documentation.

Currently, the Pipeline as Code documentation discusses Folder Computation. The issue is that this is not referred to in the Jenkins UI. The UI/process has changed and updated the name to now be Scan or Scan Organization Log, where it was previously Folder Computation. In addition to screenshot updates, this entire section's text would need to be adjusted to match, as well as creating a folder computation anchor to this section so that anything using the existing https://www.jenkins.io/doc/book/pipeline/pipeline-as-code/#folder-computation link would not be broken.

Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration.

This was first discovered with the work from #7653 updating Pipeline UI screenshots. Since the screenshots would not match the text, we decided to separate this specific section and create an issue.

Are you interested in contributing a fix?

I am interested in helping with the fix, along with @ShrushtiDesai who was working on screenshots for the Pipeline documentation.

[Mr-TAGORE3944]

Hi @kmartens27 ,

Thanks for outlining the issue so clearly! I’d be happy to help with updating the documentation to reflect the new terminology and UI changes. I can start by working on the text adjustments to replace "Folder Computation" with "Scan" or "Scan Organization Log" as appropriate, and I’ll ensure the screenshots align with the updated terms.

I’ll also set up an anchor link for “Folder Computation” to avoid breaking any existing references. I’ll coordinate with @ShrushtiDesai to ensure our updates are consistent and capture all necessary changes.

Let me know if there’s any specific guidance or if I should be aware of any other related sections to check.

Looking forward to contributing!

[kmartens27]

Hi @Mr-TAGORE3944, thank you for sharing your interest in working on this!

In terms of what to look out for, I would say just take notes as you go through the configuration so you know which text needs to be updated. If it seems like the entire section needs to be reworked, I'm happy to help with the rewriting.

For the link, it may be worth creating an attribute within the documentation. The attribute would allow you to create a sort of anchor that can retain the original https://www.jenkins.io/doc/book/pipeline/pipeline-as-code/#folder-computation URL.

Please reach out if you have any questions or concerns as you go progress, and if this is your first time contributing to the Jenkins project, our contributing guide has information on how to fork and work on your jenkins.io clone repo.

[ShrushtiDesai]

Hi @kmartens27,

I’ve been looking into the specific version of Jenkins where the Folder Computation feature was initially introduced to better understand its evolution and guide necessary documentation updates. I checked the Jenkins release changelog but couldn’t find any explicit references to Folder Computation.

Based on the date in the screenshot, it seems that Jenkins 1.639 was the version used.

It would be helpful to know if there were any subsequent versions where this feature was modified or removed, as this will assist in updating the documentation accurately.

[kmartens27]

Hi @ShrushtiDesai, I did the same search to try and find out if there was a specific release where this was updated, but could not find a specific Jenkins release that included this change.

I did find a JIRA issue referring to this, which indicates that it was updated as a result of the GitHub Organization Folder plugin. However, this plugin has since been deprecated and its functionality is now included in the GitHub Branch Source plugin. Again, there doesn't seem to be a specific entry in that changelog where the JIRA is mentioned, but it may not have been something intended to include in the changelog.

I don't believe the steps/process changed much for users, as one would still need to configure the organization folder/repository as described and you would access the scans in a similar workflow. However, if there are more drastic changes needed, we can address them accordingly.

[ShrushtiDesai]

Hi @kmartens27,

Regarding the issue you mentioned Rename Folder Computation it seems the feature falls under the GitHub Organization Folder, where Folder Computation has been replaced by Rescan Organization. Based on this, I think a screenshot of the Scan Organization log that i applied while working on Pipeline Documentation update would be appropriate.

I’d still like to get a look at the "before and after" UI in Jenkins for clarity. I’ll take a few days to try downloading the relevant Jenkins versions if they’re available and possible, to understand the changes better. If that’s not feasible, we could proceed based on this issue and treat it as part of the GitHub Organization Folder where the Folder Computation is now renamed as Scan Organization Log.

If @Mr-TAGORE3944 has any suggestions or findings, I’d be glad to hear them as well. What are your thoughts?

Let me know your suggestions.

[kmartens27]

Hi @ShrushtiDesai, I believe you're absolutely correct on what's been changed. I don't believe the overall steps/process has changed, so it might just be an update of the terminology. If you're unable to set up an older jenkins version (which is absolutely okay) we can proceed with updating the text accordingly and just make sure that we've got all the mentions of "folder computation".

[ShrushtiDesai]

Hi @kmartens27,

I successfully installed Jenkins version 1.639 with Java 7 and downloaded the GitHub Organization Folder plugin to explore the Folder Computation feature. When creating a new item of type GitHub Organization I observed that Folder Computation is available, providing logs for the scans.

According to the latest UI, this functionality is renamed as Scan Organization Log and it excludes the Log and Run Now options that were originally part of Folder Computation. Additionally, the branch indexing functionality mentioned in this issue now appears under the Multibranch Pipeline type, where the repository is scanned.

So, it seems that when the GitHub Organization Folder plugin was deprecated, and its functionality was moved into the Branch Source plugin, the Folder Computation section may have been removed and replaced with Scan Organization Log while branch indexing transitioned to Scan Multibranch Pipeline Log under the Multibranch Pipeline type.

The UI update is confirmed, so we can proceed with the documentation update. Could you provide guidance on how the content should be revised?

[kmartens27]

Hi @ShrushtiDesai, thanks very much for all the work to confirm!

In terms of what should change with the content:

• We already know the screenshots need to be updated (since you have done that work previously).

• The section header will need to be changed to Multibranch and Organization Folder Scan (or something similar).
  - There must be an anchor link added a line above the section header with the current link so that URLs relying on this do not break.

• For an example of how the text should be updated:
  - The first line of Multibranch Pipeline projects and Organization Folders extend the existing folder functionality by introducing 'computed' folders. can be changed to Multibranch Pipeline projects and Organization Folders extend the existing folder functionality by scanning the source repository or organization.
  - The second line This computation, in the case of Multibranch Pipeline projects, creates child items for each eligible branch within the child.' would need to be updated to This scan, in the case of Multibranch Pipeline projects, creates child items for each eligible branch within the child.The first example requires more editing/revising, while the second one needs just the one terminology update. The scan is performing the same functions as described, so only the termcomputation` needs to be updated.

• In most cases, folder computation and computation can be replaced with scan, scanning, or scans.

Let me know if that helps clarify, or if you have any questions or concerns about what needs to be done!