Jenkins

The Jenkins core project uses a structured hierarchy of roles to manage its mission-critical codebase. Understanding these roles helps you know how to contribute and how to progress within the project.

Roles

• Contributor: Anyone can submit pull requests (PRs) or review changes. No special preconditions are required.
• Issue Triage Team Member: Reviews incoming GitHub issues (bugs, enhancements). No special permissions required.
• Core Pull Request Reviewer: Regularly reviews PRs and guides newcomers. They have Triage permissions to manage PRs, request reviews, and prepare changelog drafts. GitHub team: @jenkinsci/core-pr-reviewers.
• Core Maintainer: Has Write permissions and can merge PRs. They are responsible for regular reviews, bringing PRs to closure (merging or closing), monitoring weekly releases, and triaging critical issues. GitHub team: @jenkinsci/core.
• Release Team Member: Responsible for weekly and LTS releases. They have Write permissions and can trigger release Pipelines.

The Ladder (Progression)

1. Contributors start by submitting PRs or commenting.
2. Core PR Reviewers are nominated via the Jenkins Developer Mailing List (self-nomination is allowed) and decided by consensus or governance meeting.
3. Core Maintainers follow the same nomination process as PR Reviewers but must also sign the Individual Contributor License Agreement (ICLA).
4. Release Team Members are assigned by the Jenkins Release Officer.

Core maintainers use specific labels and workflows to signal the status of a pull request.

Acceptance Process

When a PR is ready to be merged, the assignee applies the ready-for-merge label. This starts a countdown period (typically ~24 hours).

Example Acceptance Message:

This PR is now ready for merge. We will merge it after approximately 24 hours if there is no negative feedback. Please see the merge process documentation for more information about the merge process. Thanks!

Rejection Process

If a PR cannot proceed (due to incomplete action items, failed negotiations, or impracticality), the assignee follows these steps:

1. Apply the stalled label.
2. Apply the proposed-for-closed label.
3. Close the PR with a respectful rejection message stating the objective reasoning.

Example Rejection Message:

I am closing this PR due to <insert reasoning here>. On behalf of the core team, I would like to thank you for your contribution. Even though this PR did not make it across the finish line, it was a promising start! I continue to encourage you (or anyone else who is interested) to pick up this effort and drive it to completion. Thanks!

### Acceptance Example
> This PR is now ready for merge. We will merge it after approximately 24 hours if there is no negative feedback. Please see the merge process documentation for more information about the merge process. Thanks!

### Rejection Example
> I am closing this PR due to <insert reasoning here>. On behalf of the core team, I would like to thank you for your contribution. Even though this PR did not make it across the finish line, it was a promising start! I continue to encourage you (or anyone else who is interested) to pick up this effort and drive it to completion. Thanks!

Before a pull request can be merged into the weekly release, it must pass a multi-step checklist.

Step 1: Maintainer Checklist

• Compliance: PR must follow the pull request template.
• Approvals: At least 2 approvals are required, with no outstanding requests for change.
• Conversations: All discussions must be resolved, or reviewers must explicitly signal they are not blocking (e.g., using the term "nit").
• Changelog:
  • Entries in the PR title/description must be correct.
  • Proper changelog labels must be set for automatic generation.
  • If the change requires admin awareness during upgrades, the upgrade-guide-needed label must be present and a Proposed upgrade guidelines section included in the PR title.
• LTS Readiness: If the change is a candidate for LTS, it must be labeled lts-candidate.

Step 2: Timing and Risk

Avoid merging risky or very large changes during the week before an LTS release (weeks 3, 7, 11, 15, etc.). This ensures the security team has capacity to prepare fixes for the weekly line. If a PR is ready but the timing is bad, use the on-hold label and provide an explanation.

Issue triage ensures that bug reports and enhancement requests are legitimate, correctly categorized, and routed to the right maintainers.

Initial Triage Steps

1. Verify Component: Ensure the issue is in the correct repository (e.g., jenkins, remoting, winstone). Transfer if necessary.
2. Verify Type: Use Bug for bug reports; all other types are treated as requests for enhancement (RFE).
3. Verify Metadata: Check Jenkins version, environment, and relevant labels (e.g., jcasc-compatibility, ux).
4. Handle Security Issues: If a vulnerability is reported publicly, request a core maintainer to delete the issue and re-report it to the SECURITY project.
5. Label Regressions: If a clear root cause is found, set the regression label and CC the relevant contributors.
6. Resolve Support Requests: Redirect users seeking support to the community forum, mailing lists, or chats. Do not use the issue tracker as a support portal.
7. Resolve Duplicates: Close duplicate issues and link to the original.

Advanced Triage (Maintainers)

• Confirm Defects: Attempt to reproduce the issue. If legitimate, confirm it in a comment.
• Newcomer-Friendly: If an issue is simple, add the newbie-friendly label to encourage new contributors.
• Scrubbing Stale Issues:
  • Resolve untriaged issues that lack reproduction data after a 2-week timeout using Incomplete or Cannot reproduce resolutions.
  • Close obsolete issues caused by feature removals or component migrations.

Jenkins uses different strategies for merging Pull Requests (PRs) depending on the commit history and maintainer requirements:

When PRs are merged as-is (no squash)

• The PR contains a single commit with a reasonable message.
• The PR contains multiple atomic commits, where each commit has a reasonable message and can be compiled independently (e.g., a commit to reproduce an issue in tests followed by a commit to fix it).
• Multiple authors explicitly request to keep the commit history as is (GitHub co-authorship is supported).

When PRs are squashed

• Core maintainers decide to squash the PR, typically indicated by adding the squash-merge-me label during review.
• The conditions for merging as-is (atomic commits or single clean commit) are not met.

Review Exceptions

• Low-risk changes: Small changes with the skip-changelog label may require only one approval, provided both the author and approver have write access to the repository. Note that the standard 24-hour waiting period still applies.
• Bypassing review: Release Team members may bypass the standard review/merge process only to unblock a security release.

Pull request reviews in Jenkins core focus on feasibility, compatibility, and quality. Reviewers are not just checking code, but acting as product managers for the ecosystem.

Review Goals

• Verifying Feasibility: Evaluate if a change makes sense globally. If the motivation is unclear, use the needs-justification label.
• Ensuring Compatibility: Maintain backward compatibility (feature, binary, and API). Use tools like usage-in-plugins to check impact.
• Maintaining Code Quality: Ensure test coverage for new functionality, documentation for new APIs, and adherence to readability standards.
• Code Style: While not strictly enforced across the whole codebase, new code should follow the Oracle Java Code Conventions. For existing code, only fix formatting on the lines actually affected to keep diffs minimal.
• Maintaining Documentation: Encourage contributors to update documentation at jenkins.io/doc/. If documentation is missing, use the needs-docs label.
• Building Consensus: Use the Jenkins Developer Mailing List for discussions. If consensus cannot be reached, a vote at a Jenkins Governance Meeting may be required.

Bringing PRs to Closure

Core maintainers use the Assignee field to signal a commitment to bring a PR to closure (either merging or rejecting).

• One Assignee: To avoid ambiguity, at most one core maintainer should be assigned to a PR.
• Actionable Feedback: Maintainers should steer discussions toward clear, justified action items.
• Negotiating Scope: Maintainers should attempt to find a "good enough" middle ground to avoid chasing contributors away.
• Voting: If consensus fails, a vote can be called. A -1 vote from a core maintainer is a strong objection that stops the PR until withdrawn or outvoted, and it must be accompanied by a technical justification.