Development Guide

Guidelines for extending the shared library, adding jobs, and contributing.

Local Setup

For contributors extending the project, cloning the repository is convenient; for operators, use the distributed bundle without cloning.

If developing locally, clone once and start master:

git clone https://gitlab.com/your-org/friendly-jenkins.git
cd friendly-jenkins/jenkins-master
docker compose up -d

(Optional) Mount shared library for live edits:

# docker-compose.yml
services:
  jenkins:
    volumes:
      - ../shared-library:/var/jenkins_home/qa-library:ro

Enable hot reload in casc.yaml:

globalLibraries:
  libraries:
    - name: "qa-shared"
      retriever:
        legacySCM:
          scm:
            $class: "filesystem.FileSystemSCM"
            path: "/var/jenkins_home/qa-library"
            clearWorkspace: false

Adding a Pipeline Step

Place Groovy steps in shared-library/vars/.
Document parameters and return values in Javadoc comments.

Example skeleton:

/**
 * Validate environment configuration
 * @param envName Name of the environment
 * @return Map with validation results
 */
def call(String envName) {
    ansiColor('xterm') {
        stage('Validate Environment') {
            // implementation
        }
    }
}

Testing Changes

Compose up the master and run jobs against sample templates.
For library-only changes, mount the library locally and rerun the job.
Optional: add Spock specs under test/ if you maintain a Groovy test harness.

Code Style

Prefer string interpolation over concatenation.
Use explicit error messages; fail fast when inputs are missing.
Keep steps idempotent where possible (backups before updates, locks around mutations).

Contributing

Follow Conventional Commits (e.g., feat: …, fix: …, docs: …).
Open feature branches (feature/<topic>) and submit merge requests with context and tests.
Include documentation updates alongside code changes.