Merge pull request #8 from jenkinsci/fix/duplicate-changelog-prevention

Fix/duplicate changelog prevention

Author: ibain

CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to the Jenkins Diversion SCM Plugin will be documented in this file.
 
+> **Note:** Starting December 2025, versions are identified by commit number rather than semantic versioning.
+
+## 2025-12-09
+
+### Fixed
+- **Automatic duplicate commit prevention**: When a library checkout occurs, the plugin now checks if the pipeline's SCM is configured to use the same Diversion repository. If so, the library writes an empty changelog, preventing duplicate commits in the build status grid. This works automatically without requiring any user configuration changes.
+
+### How It Works
+During library checkout, the plugin:
+1. Accesses the pipeline job via `build.getParent()`
+2. Uses reflection to get `CpsScmFlowDefinition` (for "Pipeline script from SCM" jobs)
+3. Extracts the configured SCM's repository ID
+4. Compares with the library's repository ID
+5. If **same repo**: writes empty changelog → prevents duplicates
+6. If **different repo**: writes normal changelog → both changelogs shown
+
+### Technical Details
+- Added `getPipelineRepositoryId()` method using reflection to access `WorkflowJob.getDefinition().getScm()`
+- Library checkout stores repo info and checks pipeline config before writing changelog
+- Empty changelog written for same-repo cases: `<changelog></changelog>`
+- Console output shows detection: "Library and pipeline use same repository (dv.repo.xxx) - skipping library changelog"
+
+### Tested
+- **Environment**: Local Docker Jenkins (jenkins/jenkins:latest)
+- **Test case**: Pipeline job with `@Library` from same Diversion repo as pipeline script
+- **Before fix**: Build status grid showed "2 commits" (duplicates)
+- **After fix**: Build status grid shows "1 commit" (correct)
+- **Console verification**: 
+  ```
+  Pipeline is configured with Diversion repository: dv.repo.ce476570-2c46-4fc4-8c4a-541dd6a6d204
+  Library and pipeline use same repository (dv.repo.ce476570-2c46-4fc4-8c4a-541dd6a6d204) - skipping library changelog to prevent duplicates
+  ```
+
+### Improved
+- **README cleanup**: Moved development instructions to DEVELOPMENT.md and version history to CHANGELOG.md
+- **Better troubleshooting docs**: Added troubleshooting entry for duplicate commits issue
+- **Configuration script**: Updated `configure-diversion-library.groovy` to set `includeInChangesets(false)` by default (as a fallback)
+
+---
+
 ## [1.0.1] - 2025-11-19
 
 ### Fixed

README.md

@@ -96,6 +96,15 @@ The plugin will automatically search for a `.groovy` file matching your job name
    - **Default Branch**: Branch to checkout (dropdown populates automatically)
    - **Library Base Path**: Path to your folder containing `vars/`, `src/`, `resources/` directories (e.g., `Meta/Jenkins/SharedLib`)
 
+#### Important: Prevent Duplicate Commits in Changelog
+
+**If your pipeline script and shared library are in the same Diversion repository**, you should **uncheck** the "Include @Library changes in job recent changes" option. Otherwise, Jenkins will show duplicate commit entries in the build status grid (one from the library checkout and one from the script checkout).
+
+- In the library configuration, uncheck: **"Include @Library changes in job recent changes"**
+- Or when configuring via Groovy script, add: `libraryConfig.setIncludeInChangesets(false)`
+
+This is recommended whenever the library is stored in the same repository as your pipeline scripts to avoid confusing duplicate entries.
+
 #### Using the Library in Pipeline Jobs:
 
 ```groovy
@@ -163,69 +172,7 @@ This plugin integrates with the [Diversion API](https://docs.diversion.dev/api-r
 
 ## Development
 
-### Building the Plugin
-
-```bash
-# Clean and compile
-mvn clean compile
-
-# Run tests
-mvn test
-
-# Package plugin (skips tests for faster builds)
-mvn clean package -DskipTests
-
-# Run Jenkins with plugin
-mvn hpi:run
-```
-
-### Project Structure
-
-```
-src/main/java/io/superstudios/plugins/diversion/
-├── DiversionSCM.java                  # Legacy SCM implementation
-├── DiversionSCMSource.java            # Modern SCM (Global Libraries)
-├── DiversionSCMFileSystem.java        # File system for library loading
-├── DiversionSCMFileSystemBuilder.java # Builder for file systems
-├── DiversionSCMHead.java             # SCM head (branch) representation
-├── DiversionSCMRevision.java         # SCM revision (commit) representation
-├── DiversionSCMRevisionState.java    # State tracking for builds
-├── DiversionChangeLogParser.java     # Parses changelog XML
-├── DiversionChangeLogSet.java        # Change log set container
-├── DiversionChangeLogEntry.java      # Individual changelog entry
-├── DiversionApiClient.java           # Diversion API client
-├── DiversionUIHelper.java            # Shared UI helper methods
-├── DiversionRepository.java          # Repository model
-├── DiversionBranch.java              # Branch model
-├── DiversionCommit.java               # Commit model
-├── DiversionFile.java                # File model
-├── DiversionAuthor.java              # Author model
-└── DiversionTag.java                 # Tag model (for future use)
-
-src/main/resources/
-├── index.jelly                       # Plugin index page
-└── io/superstudios/plugins/diversion/
-    ├── DiversionSCM/
-    │   ├── config.jelly              # Legacy SCM configuration UI
-    │   └── help-repositoryId.html    # Help text
-    ├── DiversionSCMSource/
-    │   ├── config.jelly              # Modern SCM configuration UI
-    │   └── help-libraryPath.html    # Help text
-    ├── DiversionChangeLogEntry/
-    │   ├── digest.jelly              # One-line summary template
-    │   └── index.jelly               # Detail page template
-    └── DiversionChangeLogSet/
-        └── index.jelly               # ChangeLogSet list template
-```
-
-### Code Quality
-
-The plugin follows Jenkins plugin best practices:
-- **Code Deduplication**: Shared UI logic in `DiversionUIHelper` class
-- **Proper Error Handling**: Graceful fallbacks for API failures
-- **Null Safety**: Comprehensive null checks throughout
-- **Documentation**: Javadoc comments on all public methods
-- **No Stale Code**: All code is actively used
+For build instructions, project structure, and contribution guidelines, see [DEVELOPMENT.md](DEVELOPMENT.md).
 
 ## Troubleshooting
 
@@ -256,40 +203,15 @@ The plugin follows Jenkins plugin best practices:
    - Check that commits exist in the repository
    - Verify the changelog XML file exists in the build directory
 
-## Recent Improvements
-
-### Version 1.0.1
-
-- ✅ **Fixed folder-scoped credentials**: Credentials created in folders now work correctly at runtime
-- ✅ **Credential tracking**: Added credential usage tracking for reporting
-- ✅ **Modern Credentials API**: Updated to use modern API pattern (no Authentication parameter)
-- ✅ **UI improvements**: Using `StandardListBoxModel` for proper credential display
-- ✅ Updated to Java 17 (matches Jenkins baseline requirements)
-- ✅ Migrated to BOM-based dependency management (cleaner, more maintainable)
-- ✅ Updated Jenkins baseline to 2.504.3
-- ✅ Improved dependency version management using Jenkins BOM
-- ✅ Updated parent POM to version 5.28 (Jenkins requirement)
-- ✅ Replaced direct dependencies with Jenkins API plugins:
-  - `httpclient` → `apache-httpcomponents-client-4-api`
-  - `jackson-databind` → `jackson2-api`
-- ✅ Added security scanning workflow and dependency update automation
-- ✅ **Security Enhancements:**
-  - Credential enumeration protection (permission checks before accessing credentials)
-  - CSRF protection (`@RequirePOST` annotations on external API calls)
-  - Proper permission checks using `hasPermission()` for better UX
-  - Proxy support with authentication via `ProxyConfiguration.newHttpClient()`
-  - All security findings from Jenkins CodeQL scans resolved
-
-### Version 1.0.0
-
-- ✅ Fixed changelog detail page display
-- ✅ Added commit ID display in Changes page list
-- ✅ Fixed changelog entry parent relationships
-- ✅ Improved global library reload detection (uses commit timestamps)
-- ✅ Code deduplication (created `DiversionUIHelper` class)
-- ✅ Removed stale code (workspaceId field)
-- ✅ Enhanced error handling and null safety
-- ✅ Improved Jelly templates with proper null checks
+6. **Duplicate Commits in Build Status Grid**
+   - This happens when your pipeline script and shared library are in the same repository
+   - Jenkins creates changelog entries for both the script checkout and library checkout
+   - **Fix**: In the library configuration, uncheck "Include @Library changes in job recent changes"
+   - Or add `libraryConfig.setIncludeInChangesets(false)` when configuring via Groovy
+
+## Changelog
+
+For version history and recent improvements, see [CHANGELOG.md](CHANGELOG.md).
 
 ## Contributing
 

src/main/java/io/superstudios/plugins/diversion/DiversionSCM.java

@@ -220,17 +220,17 @@ public void checkout(@NonNull Run<?, ?> build, @NonNull Launcher launcher,
             }
 
             // Write changelog file if provided
-            // Use a flag to ensure we only write changelog once per build (prefer script checkout over library)
+            // Smart duplicate prevention: During library checkout, we check if the pipeline's
+            // SCM is configured to use the same Diversion repository. If so, we skip writing
+            // the library changelog to prevent duplicates.
             if (changelogFile != null) {
                 boolean shouldWriteChangelog = false;
+                boolean skipForSameRepo = false;
+                
+                // Use build ID to track state across checkouts
+                String buildKey = build.getExternalizableId();
 
-                // Check if this is the first checkout for this build
                 synchronized (build) {
-                    String changelogKey = "diversion.changelog.written";
-                    Object changelogWritten = build.getAction(hudson.model.ParametersAction.class);
-                    
-                    // Use build number + hash as a simple way to track if we've written changelog
-                    String buildKey = build.getExternalizableId();
                     String alreadyWritten = System.getProperty(buildKey + ".changelog");
 
                     if (alreadyWritten == null) {
@@ -241,22 +241,41 @@ public void checkout(@NonNull Run<?, ?> build, @NonNull Launcher launcher,
                             System.setProperty(buildKey + ".changelog", "script");
                             listener.getLogger().println("Creating changelog (script checkout)...");
                         } else {
-                            // Library checkout - only write if it's the first checkout
-                            shouldWriteChangelog = true;
-                            System.setProperty(buildKey + ".changelog", "library");
-                            listener.getLogger().println("Creating changelog (library checkout)...");
+                            // Library checkout - check if pipeline uses the same repo
+                            String pipelineRepoId = getPipelineRepositoryId(build, listener);
+                            if (pipelineRepoId != null && pipelineRepoId.equals(repositoryId)) {
+                                // Same repo! Skip library changelog to prevent duplicates
+                                skipForSameRepo = true;
+                                System.setProperty(buildKey + ".changelog", "library-skipped");
+                                listener.getLogger().println("Library and pipeline use same repository (" + repositoryId + ") - skipping library changelog to prevent duplicates");
+                            } else {
+                                // Different repo or couldn't determine - write changelog
+                                shouldWriteChangelog = true;
+                                System.setProperty(buildKey + ".changelog", "library");
+                                if (pipelineRepoId != null) {
+                                    listener.getLogger().println("Library uses different repository than pipeline - creating changelog");
+                                } else {
+                                    listener.getLogger().println("Creating changelog (library checkout)...");
+                                }
+                            }
                         }
-                    } else if (alreadyWritten.equals("library") && !isLibraryCheckout) {
-                        // We wrote changelog for library, but now we have a script checkout
-                        // Overwrite with script checkout (preferred)
+                    } else if ((alreadyWritten.equals("library") || alreadyWritten.equals("library-skipped")) && !isLibraryCheckout) {
+                        // Library checked out first, now script checkout
                         shouldWriteChangelog = true;
                         System.setProperty(buildKey + ".changelog", "script");
-                        listener.getLogger().println("Updating changelog (script checkout - preferred over library)...");
+                        listener.getLogger().println("Creating changelog (script checkout)...");
                     } else {
                         listener.getLogger().println("Skipping changelog (already written for this build)");
                     }
                 }
 
+                // Write empty changelog if we're skipping for same-repo
+                if (skipForSameRepo) {
+                    try (java.io.FileWriter writer = new java.io.FileWriter(changelogFile, java.nio.charset.StandardCharsets.UTF_8)) {
+                        writer.write("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<changelog>\n</changelog>\n");
+                    }
+                }
+                
                 if (shouldWriteChangelog) {
                     try {
                         // Get the latest commit for this build
@@ -465,6 +484,44 @@ public hudson.scm.ChangeLogParser createChangeLogParser() {
         return new DiversionChangeLogParser();
     }
 
+    /**
+     * Get the repository ID configured for the pipeline's SCM (if it's a DiversionSCM).
+     * This allows us to detect when a library checkout is from the same repo as the pipeline,
+     * so we can skip writing duplicate changelog entries.
+     * 
+     * @param build The current build
+     * @param listener For logging
+     * @return The repository ID if the pipeline uses DiversionSCM, null otherwise
+     */
+    private String getPipelineRepositoryId(Run<?, ?> build, TaskListener listener) {
+        try {
+            Job<?, ?> job = build.getParent();
+            
+            // Check if this is a WorkflowJob (pipeline)
+            if (job.getClass().getName().equals("org.jenkinsci.plugins.workflow.job.WorkflowJob")) {
+                // Use reflection to access the flow definition
+                java.lang.reflect.Method getDefinition = job.getClass().getMethod("getDefinition");
+                Object definition = getDefinition.invoke(job);
+                
+                if (definition != null && definition.getClass().getName().equals("org.jenkinsci.plugins.workflow.cps.CpsScmFlowDefinition")) {
+                    // This is a "Pipeline script from SCM" job
+                    java.lang.reflect.Method getScm = definition.getClass().getMethod("getScm");
+                    Object scm = getScm.invoke(definition);
+                    
+                    if (scm instanceof DiversionSCM) {
+                        String pipelineRepoId = ((DiversionSCM) scm).getRepositoryId();
+                        listener.getLogger().println("Pipeline is configured with Diversion repository: " + pipelineRepoId);
+                        return pipelineRepoId;
+                    }
+                }
+            }
+        } catch (Exception e) {
+            // Couldn't determine pipeline SCM - not a problem, we'll just write the changelog
+            listener.getLogger().println("Note: Could not determine pipeline SCM type: " + e.getMessage());
+        }
+        return null;
+    }
+    
     /**
      * Escape XML special characters
      */