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!

[ShrushtiDesai]

Hi @kmartens27,

I’d like to propose an update to the Folder Computation section. I think we can approach the updation by first describing the previous functionality, where "Folder Computation" and "Branch Indexing" were available, and then explain how these features were renamed following the deprecation of the GitHub Organization Folder plugin.

Here’s a draft of the revised section:

Multibranch Pipeline projects and GitHub Organization Folders extend Jenkins' folder functionality by introducing "computed" folders, which automatically manage their contents by dynamically creating and updating child items.

• Multibranch Pipeline Projects: Previously, the computed folder functionality was located under the Branch Indexing tab, where Jenkins would generate child items for each eligible branch within a repository and automatically update the pipeline list as branches changed. This feature has now been renamed to Scan Multibranch Pipeline Log.

• GitHub Organization Projects: Originally, the computed folder functionality was found under the Folder Computation tab, where it populated repositories as individual Multibranch Pipelines and provided insights into branch and repository scans. This functionality has now been renamed to Scan Organization Log.

Following the deprecation of the GitHub Organization Folder plugin and its integration into the Branch Source plugin, this updated log section now appears as a streamlined interface without the previous Log and Run Now options.

Folders scans can automatically trigger scans through webhook callbacks whenever branches or repositories are created or removed. Scans can also be configured to run periodically via the Build Trigger settings, which default to a re-scan after one day of inactivity.

Please let me know your thoughts and if you have any suggestions on this approach. Do you think it’s a good direction to proceed with?

[kmartens27]

Hi @ShrushtiDesai, I like the idea and organization of this update. It provides the background while informing users of what to expect now and clarifies that the functions have been renamed as opposed to removed or completely changed. I think that is a great direction to proceed with, and if others feel strongly one way or another, we can always address those in the PR.

[ShrushtiDesai]

Hi @kmartens27,

I wanted to clarify my previous draft, as I realize it may have led to some misunderstandings. The initial version suggested that Run Now and Log were combined into Scan Organization Log for GitHub Organization Folders and Scan Multibranch Pipeline Log for Multibranch Pipelines. However, that's not the case.

In the updated Jenkins UI, Run Now and Log have been removed from their original tabs and are now treated as separate options: Scan Organization Log and Scan Organization Now for GitHub Organization projects, and Scan Multibranch Pipeline Log and Scan Multibranch Pipeline Now for Multibranch Pipeline projects.

Here is the revised and complete draft version for Folder Computation section:

Folder Computation

Multibranch Pipeline projects and GitHub Organization Folders extend Jenkins' folder functionality by introducing computed folders, which automatically manage their contents by dynamically creating and updating child items.

• Multibranch Pipeline Projects: Previously, the computed folder functionality was located under the Branch Indexing tab, which included Run Now and Log options. Jenkins would generate child items for each eligible branch within a repository and automatically update the pipeline list as branches changed. In the updated version, these options are no longer under a specific tab and have been renamed to Scan Multibranch Pipeline Log and Scan Multibranch Pipeline Now.

• GitHub Organization Projects: Originally, the computed folder functionality appeared under the Folder Computation tab, with Run Now and Log options. This functionality populated repositories as individual Multibranch Pipelines and provided insights into branch and repository scans. In the updated version, these options are no longer under a tab; they have been renamed to Scan Organization Log and Scan Organization Now.

These updates followed the deprecation of the GitHub Organization Folder plugin and its integration into the GitHub Branch Source plugin.

Folder scans can be automatically triggered through webhook callbacks whenever branches or repositories are created or removed. Scans can also be configured to run periodically via the Build Trigger settings, which default to a re-scan after one day of inactivity.

![Build Trigger settings image here]

The log from the last attempt to scan the organization is available in the Scan Organization Log. If the scan doesn’t produce the expected set of repositories, the log may contain useful information to help diagnose the issue.

![Scan Organization Log image here]

Let me know your thoughts and any suggestions on this revision, and if you think a title change might be beneficial for clarity. If everything looks good, I'll proceed to create a pull request.

[kmartens27]

Hi @ShrushtiDesai sorry for the delay, I was sick and away from my computer. I like the suggestions you've provided and the context you've added here. I think this is a good way to update the text and inform readers of what changes have occurred. Please proceed with creating a pull request for this update and thank you again for all your work on this!

[ShrushtiDesai]

@kmartens27 no worries i'll proceed with the pull request.

[ShrushtiDesai]

Hi @kmartens27,
I apologize for the inconvenience. After making the changes, I noticed that I still had the option to force push. I considered deleting the branch from my repository to start fresh, but unfortunately, this led to the pull request being closed, and I’m unable to reopen it now.
Could you please advise on the best way to proceed? Should I create a new pull request with the updated changes, or is there another way to recover the previous one?
Really sorry for this mistake again!

[kmartens27]

Hi @ShrushtiDesai, it appears that the branch itself was deleted, so it would not be possible to re-open the original pull request. The best course of action would be to create a new pull request. I know this is not ideal, but you would be able to get the work and suggestions from https://github.com/jenkins-infra/jenkins.io/pull/7692/files as it has not been deleted.

Sorry about that. Also, the reason I suggested not force pushing is to avoid any unwanted changes or pushing changes that were made before your work on the branch was completed. Basically, trying to avoid what happened in #7642.

[kmartens27]

Closing this as #7694 has updated the documentation as described.