:toc: :toclevels: 3 = Documentation for core maintainers toc::[] Jenkins core is a central component of the project which serves millions of users, and it is critical to maintain it in a good shape. We want to ensure quality of the integrated changes and continuity of the project, and hence the Jenkins core pull request review and merge process is more sophisticated than for the majority of plugins. == Scope of the document This document applies to the following components: * Jenkins core * Libraries included into the Jenkins core * Core components like Winstone, Executable WAR, etc. Jenkins Remoting library is not in the scope for this document, because it is handled as a sub-project with independent maintainer team. Remoting updates in the core are subject to the process though. == Team === Communication channels * Mailing list: link:https://groups.google.com/d/forum/jenkinsci-dev[Jenkins Developer Mailing List] * Chat for runtime Jenkins release coordination takes place in link:https://matrix.to/#/#jenkins-release:matrix.org[#jenkins-release:matrix.org]. ** All async communications should go to the developer mailing list === Roles * Contributor * Issue Triage Team Member * Core Pull Request Reviewer * Core Maintainer ** Pull Request Assignee * Release Team Member **Contributors** submit pull requests to the Jenkins core and review changes submitted by others. There are no special preconditions to do so. Anyone is welcome to contribute. **Issues Triage Team Members** review the incoming issues submitted in Jenkins Jira: bug reports, requests for enhancement, etc. Special permissions are not required to take this role or to contribute. Anyone is welcome to start contributing (see the <>). **Core Pull Request Reviewers** is a team for contributors who are willing to regularly review Jenkins pull requests and eventually become Jenkins core maintainers. They get https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization[Triage permissions] so that they can manage pull requests, request reviews and prepare changelog drafts in the pull request description. Their main responsibility is to triage and review the incoming pull requests and to guide newcomer contributors who are not familiar with the project's processes. GitHub team: link:https://github.com/orgs/jenkinsci/teams/core-pr-reviewers[@jenkinsci/core-pr-reviewers]. **Core Maintainers** get `Write` permissions in the repository, and hence they are able to merge pull requests. Their responsibility is to perform pull request reviews on a regular basis and to bring pull requests to closure, either by merging ready pull requests towards weekly releases (`master` branch) or by closing pull requests that are not ready for merge because of submitter inaction after an extended period of time. Core maintainers make a commitment to bringing a pull request to closure by becoming an **Assignee.** They are also responsible to monitor the weekly release status and to perform triage of critical issues. GitHub team: link:https://github.com/orgs/jenkinsci/teams/core[@jenkinsci/core]. **Release Team Members** are responsible for Jenkins weekly and LTS releases. Led by the link:https://www.jenkins.io/project/team-leads/#release[Jenkins Release Officer], they initiate releases and backport changes into the link:https://www.jenkins.io/download/lts/[Stable release line]. Team members get `Write` permissions in the Jenkins core repository, and they also get permissions to trigger release Pipelines. LTS release steps are documented in link:https://github.com/jenkins-infra/release/blob/master/.github/ISSUE_TEMPLATE/1-lts-release-checklist.md[jenkins-infra/release] === Ladder * **Contributors**. Anyone can participate. There is no precondition except having a GitHub account, just submit pull requests or comment on existing ones! * **Core Pull Request Reviewers** can be nominated by contributors in the link:https://groups.google.com/d/forum/jenkinsci-dev[developer mailing list]. Self-nomination is fine. The Decision is made by a consensus in the mailing list or via voting at the link:https://www.jenkins.io/project/governance-meeting/[governance meeting]. * **Core Maintainers** - same process as for Core PR reviewers. All nominees must also sign an link:https://github.com/jenkinsci/infra-cla/[Individual Contributor License Agreement] before getting permission in GitHub repositories. * **Release Team Members** are assigned by the Jenkins Release officer == Pull request review process Jenkins core is a mission-critical part of the ecosystem. We need to ensure that submitted pull requests are not only code complete, but also that they do not introduce undesired defects, breaking changes or technical debt. At the same time, we are interested to make the review process as simple as possible for contributors and maintainers. === Review goals Pull requests review in Jenkins is not just about reviewing code and accepting them if the code is OK. Core maintainers are expected to ensure feasibility and compatibility of changes, to maintain a good quality of the codebase and documentation, to ensure there is a consensus between contributors, and to bring pull requests to closure in a timely fashion, either by merging ready pull requests towards weekly releases or by closing pull requests that are not ready for merge because of submitter inaction after an extended period of time. ==== Verifying Feasibility Reviewers are expected to look at changes critically from a "product management" point of view. It's not just about the code, but also whether the change makes sense in a global/holistic way, considering existing popular plugins and the way users experience Jenkins overall. Also, not every change needs to be merged into the core. Many features would be better introduced as plugins that have separate release cycles and allow delivering changes faster. We want to extend the Jenkins core and incorporate widely used functionality and extension points there, but we try to keep the core as minimal as possible in terms of dependencies. When the motivation of the pull request is unclear, incomplete, or not entirely cogent, the pull request needs to be labeled with `needs-justification`. ==== Ensuring Compatibility The Jenkins project has a long history of backward compatibility. We accept breaking changes when it is needed (security fixes, feature deprecation and removal, etc.), but ultimately the project's goal is to retain as much compatibility as possible. It includes both feature compatibility and binary/API compatibility which is important for the plugin ecosystem. Although we have some tools (like https://github.com/jenkins-infra/usage-in-plugins[usage-in-plugins]) for checking API usages across open-source plugins, there is no way to confirm external usages in 3rd-party proprietary plugins which are also a part of the ecosystem. ==== Maintaining Code quality The code doesn't have to be perfect, but we want to ensure that all new code matches basic quality standards: test coverage for newly added functionality and fixes, documentation for newly introduced APIs, the submitted code is readable and matches the code style in the surrounding codebase, etc. ==== Code style We're aware that there are existing inconsistencies in the code, and we do not enforce a single code style across the codebase at the moment. * New code should follow the (majority) style guide. In Jenkins core, we use link:https://www.oracle.com/java/technologies/javase/codeconventions-contents.html[these Code Conventions for the Java TM Programming Language] as a default code style * Updates to existing code should only fix formatting on the lines affected anyway to keep the diff minimal. It helps reviewers focus their attention on the specifics of the change and reduces the risk of a change from one pull request creating a conflict in another pull request. ==== Maintaining documentation * Jenkins documentation is hosted on https://www.jenkins.io/doc/. When a new user-facing change is added, we should encourage contributors to update the documentation in downstream pull requests. * The Same applies to Jenkins changelogs (link:https://www.jenkins.io/changelog[weekly], link:https://www.jenkins.io/changelog-stable/[stable]) and link:https://www.jenkins.io/doc/upgrade-guide/[upgrade guidelines]: We have a semi-automated process that is based on pull request summaries and labels. Core maintainers are expected to validate the entries as a part of the pull request review/merge process. See the checklist below in the _Merge process_ section. * When the proposed change lacks sufficient documentation, use the `needs-docs` label on the pull request. ==== Building consensus Not all changes are discussed before they are submitted as pull requests. Developer mailing lists, Jira issues and JEPs are used for discussions, but sometimes the changes go straight to the pull requests. And we are fine with that, especially for small patches. Pull requests often become a venue to discuss feasibility, underlying technical decisions and design. We are fine with that as well. The pull request can be marked with `needs-more-review` to get more eyes on the change. If there is no consensus about the feasibility and implementation, code reviewers are expected to suggest proper channels for contributors to discuss their contributions. * A discussion in the link:https://groups.google.com/d/forum/jenkinsci-dev[Jenkins Developer Mailing List] is the default way to go * If no consensus can be reached on the mailing list, voting at the link:https://www.jenkins.io/project/governance-meeting/[Jenkins Governance Meeting] can be used to get a final decision. === Bringing pull requests to closure ==== Motivation An obvious goal of the project is to deliver value to end users (without incurring an undue maintenance burden), without which end users would cease use of the delivered software. A pull request represents potential value for end users, value which is only realized when the pull request is merged and delivered in a shipping release. The same goes for maintenance pull requests that do not deliver immediate value to users but improve the project's health and sustainability, for example, developer documentation updates, code quality improvements, project and test automation, etc. These pull requests also need to be merged, and it is in our best interests to do so rather sooner than later. [cols="1,1"] |=== |Optimal Outcome|Suboptimal Outcome |When a pull request is merged and delivered in a shipping release, users are rewarded with this value. |Inversely, when a pull request remains unmerged and unreleased for an extended period of time, users are deprived of this value. |=== Another explicit goal of the project is to encourage both new and seasoned contributors alike. [cols="1,1"] |=== |Optimal Outcome|Suboptimal Outcome |When a submission that is ready for merge is approved, merged, and released in a timely fashion, the contributor is more likely to contribute again. |Inversely, when a submission that is ready for merge languishes without timely approval, merge, and release, the contributor is less likely to contribute again. |When the contributor of a submission that is not _yet_ ready for merge is provided with clear, actionable, and justified feedback and when, after the action has been taken, the submission is subsequently reviewed again, approved, merged, and released in a timely fashion, the contributor is more likely to contribute again. |Inversely, when the contributor of a submission that is not _yet_ ready for merge is provided feedback without reasoning or asked questions that do not ultimately lead to a clear action item, the contributor is less likely to improve the quality of the submission. |When contributors and reviewers successfully negotiate scope, the contributor is more likely to complete the submission. |Inversely, when contributors and reviewers fail to negotiate a middle ground regarding scope, the contributor is less likely to complete the submission. |When an impractical submission is reviewed and explicitly rejected with reasoning in a timely fashion, the contributor is more likely to improve the quality of future submissions. |Inversely, when an impractical submission is ignored without an explicit rejection or rejected explicitly without reasoning, the contributor is less likely to improve the quality of future submissions. |=== For these reasons, core maintainers are expected not only to review pull requests but also to bring them to closure in a timely fashion, either by merging ready pull requests towards weekly releases or by closing pull requests that are not ready for merge after an extended period of time. As part of the process of bringing pull requests to closure, core maintainers are expected to steer discussions towards the identification of clear action items with reasoning and to explicitly reject with reasoning pull requests for which there are no clear and justified action items or for which such action items remain incomplete after an extended period of time. ==== Indicating intent to merge or close Core maintainers communicate their intention to bring a pull request to closure by adding themselves to the pull request in the **Assignees** field, through which they make a commitment to work with the contributor to either merge the pull request or to explicitly reject it. To avoid ambiguity, at most one (1) core maintainer should be assigned to a pull request. Only core maintainers should be assigned to pull requests, since a non-maintainer would be unable to fulfill the commitment by merging the pull request or explicitly rejecting it. To avoid making commitments on behalf of others that cannot be fulfilled, core maintainers should only assign pull requests to themselves and not to other core maintainers. An exception to the above would be if, following the adoption of this system, a pull request is brought to closure but remains unassigned. In that case, any core maintainer can retroactively assign the pull request to the core maintainer who merged or closed it for tracking purposes. In light of the responsibility to merge or close pull requests implied by membership on the core team, all core maintainers are strongly encouraged to regularly merge or close pull requests. ==== Providing actionable and justified feedback Once assigned to a pull request, a core maintainer should make every reasonable effort to drive the pull request to closure in a timely fashion. If further action is needed before the pull request can be accepted, this action should be explicitly requested along with the reasoning behind it. Contributors are far more likely to successfully complete action items when the reasoning behind the request is explicit and cogent. It is perfectly reasonable for the assignee or any other reviewer to ask questions, but the ultimate goal of these questions should be to arrive at clear and justified action item(s); otherwise, the process can languish for an extended period of time. It is the responsibility of the assignee to steer the discussion towards concrete and justified action item(s). ==== Providing confirmation that feedback has been addressed Once any requested actions have been taken, the assignee should make every reasonable effort to provide explicit confirmation that each action item has been completed. This gives contributors positive reinforcement and confidence that their submission is moving forward through the process, ultimately making them more likely to complete the process and contribute again. Assignees who cannot provide such confirmation in a timely fashion are strongly encouraged to remove their assignment from the pull request in order to allow another core maintainer to pick it up. If the assignee cannot respond in a timely fashion, the author or another core maintainer may ask the current assignee about their intentions; in the absence of a timely response, another core maintainer may remove the assignment. ==== Negotiating scope Not every pull request reaches a state of perfection at the end of the review process. Sometimes, requests are made that, while justified, represent an additional amount of work that the contributor may not be willing to do. In some cases it is critical to complete the additional work, but in others "you aren't gonna need it" (YAGNI). In such cases, the assignee should make a good faith effort to negotiate with the contributor to find a reasonable middle ground that is "good enough." Failure to negotiate successfully can often chase contributors away. If the additional work is simple enough and the submission is not moving forward, the assignee may consider occasionally giving the contributor a lift by completing the additional work, though this is not expected in the general case and would not be fair to the assignee if a large amount of additional work is necessary. ==== Voting process A pull request can often serve as a catalyst for a discussion in which several possible paths forward are identified. When there is no clear consensus among the core maintainers about the path forward, the assignee should call for a vote. While only core maintainers have formally binding votes, any interested parties are generally encouraged to vote, even if their votes are advisory. To avoid ambiguity, it is preferred that votes be done using https://www.apache.org/foundation/voting.html#expressing-votes-1-0-1-and-fractions[Apache conventions]. Unlike in the Apache Software Foundation, a -1 vote is not a veto but rather a very strong objection. A -1 vote by a core maintainer stops a pull request in its tracks until and unless the core maintainer withdraws the -1 vote or is outvoted by other core maintainers. To ensure that -1 votes are used prudently, the core maintainer must provide with the -1 vote a technical justification showing why the change is bad (e.g., opens a security exposure, negatively affects performance, etc.). A -1 vote without a justification is invalid and has no weight. ==== Acceptance [[acceptance]] Once a pull request has reached the point where it is ready for merge, it is time to begin the countdown period by applying the `ready-for-merge` label. To avoid ambiguity, this label should only be applied by a core maintainer who actually intends to merge the pull request. Non-maintainers, including members of the core PR reviewers team, should not start the countdown period, as this sends a signal to the contributor that their submission will be merged soon when in fact there may not be a core maintainer who has committed to merging it. To avoid making commitments on behalf of others that cannot be fulfilled, the `ready-for-merge` label should be applied by the assignee and not by another core maintainer. If the pull request does not have an assignee, applying the `ready-for-merge` label implies self-assignment, and this self-assignment may retroactively be made explicit by another core maintainer for tracking purposes. Please be mindful that people are more likely to contribute again when they are thanked for their contribution. An example acceptance message is as follows: > This PR is now ready for merge. We will merge it after approximately 24 hours if there is no negative feedback. Please see the https://github.com/jenkinsci/jenkins/blob/master/docs/MAINTAINERS.adoc#merge-process[merge process documentation] for more information about the merge process. Thanks! ==== Rejection Not all pull requests reach the point where they are ready for merge. In some cases, the pull request is close to being ready, but one or more justified action items remain incomplete. In other cases, negotiations regarding scope have reached an impasse. In other cases, the pull request is very far from being ready or is completely impractical, and no progress is being made. When a pull request is not ready for merge after an extended period of time, the assignee is responsible for completing the rejection process, first by applying the `stalled` label, then by applying the `proposed-for-closed` label, and finally by closing the pull request with a rejection message. This process should be undertaken with the utmost care and respect in order to ensure that the contributor feels welcome to contribute again. At minimum, the reasoning behind the rejection should be stated in objective and factual terms. If the proposed change might be accepted again in the future once additional action item(s) have been completed, these should be stated to allow for the original author or a different author to complete the proposed change. Please be mindful that people are more likely to contribute again when they are thanked for their contribution. An example rejection message is as follows: > I am closing this PR due to . 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! === Review non-goals Code reviews do NOT pursue the following goals: * Accepting/merging any pull request. Not everything is going to be merged, and reviewers are expected to focus on the Jenkins ecosystem integrity first. We guide contributors and help them to get their changes integrated, but it needs cooperation on both sides. It is **fine** to close invalid and inactive pull requests if there is no activity by a submitter or other contributors. When a pull request remains inactive for a month, it can be marked with the label `stalled`. If the pull request remains inactive or without consensus for yet another month, the pull request can be marked as `proposed-for-close`. The pull request should then be closed in approximately a week if this state persists. * Enforcing a particular coding style. Jenkins core has a complex codebase created by many contributors, and different files have different designs. Our main goal is to firstly have the code readable by other contributors. * Make contributors fix issues that are not related to the primary topic of the pull request ** Create follow-up issues instead, it is fine to reference them in comments so that the contributor might want to pick them up * Make contributors to have atomic commit history or to squash their pull request ** Not every contributor is a Git expert, do not request changes in the commit history unless it is necessary ** Core maintainers can squash PRs during the merge. If you feel this is important, add the link:https://github.com/jenkinsci/jenkins/pulls?q=is%3Aopen+is%3Apr+label%3Asquash-merge-me[squash-merge-me] label ** We want to keep pull requests focused when possible (one feature/fix per pull request), but we can live without it if there is no need to backport changes to the stable baseline. == Issue triage Jenkins core and most of its components use link:https://issues.jenkins.io/[Jenkins Jira] as an issue tracker. This issue tracker is open to all Jenkins users. They report defects and requests for enhancements, and then component maintainers triage issues and provide feedback to users. In the case of the Jenkins core, the *Issue Triage Team* and *Core Maintainers* are roles that are expected to process the incoming issues. These contributors perform initial triage of incoming issues and periodically scrub the issue tracker. This section provides some tips and tricks about triaging issues submitted to the Jenkins core. === Issue tracker structure Jenkins core uses the link:https://issues.jenkins.io/projects/JENKINS[JENKINS] project for issue tracking. This project is shared between the Jenkins core components and plugins, and the Jenkins core is scattered across multiple components: `core`, `remoting`, `cli`, `winstone-jetty`, etc. In addition to it, there is a default `_unsorted` component which is recommended by default for users who do not know what is the root cause of an issue they experience. Searching for all Jenkins core issues is not trivial, and we provide Jira filters for it. === How to discover untriaged issues? * Community rating in Jenkins link:https://www.jenkins.io/changelog/[Regular (Weekly)] and link:https://www.jenkins.io/changelog-stable/[LTS] releases. Such ratings allow users to reference issues they experienced with new Jenkins core releases, and it helps to discover regressions in the core causing instability or unexpected plugin failures. * link:https://issues.jenkins.io/secure/Dashboard.jspa?selectPageId=20742[Jenkins core triage board] - Lists untriaged and recent issues in the Jenkins core and bundled components. * link:https://issues.jenkins.io/secure/Dashboard.jspa?selectPageId=20340[Core maintainers board] - Lists unresolved recent regressions, unresolved recent core bugs, and popular new issues. This dashboard can be used to discover issues that **might** be related to the recent changes in the Jenkins core. === HOWTO: Initial triage Initial issue triage has the following objectives: * **Perform initial triage of an issue**. Issue triage team members are not expected to perform a full analysis of the issue (though they are welcome to do so!). The main goal is to ensure that an issue report is legitimate and that it contains enough information to be processed. It is fine to request additional information from submitters and/or to refer them to reporting guidelines: ** link:https://www.jenkins.io/participate/report-issue/[Guide: How to report an issue in Jenkins] ** link:https://github.com/jenkinsci/remoting#reporting-issues[Reporting Jenkins Remoting issues] * **Verify the issue component**. It is essential to ensure that the `component` field references the right component (the Jenkins core, a plugin, etc.) so that an issue can be discovered and processed by a component maintainer. When moving an issue, assign the issue to the `automatic` assignee so that the maintainer gets a notification. Not all components have a default assignee, and it is perfectly fine to leave the assignee field empty. * **Verify the issue type**. `Bug` should be used for bug reports. All other issue types are considered as requests for enhancements, and there is no practical difference for the Jenkins core. * **Verify the issue metadata**: Jenkins version, environment, labels, etc. Such metadata is useful for further triage and issue discoverability. There are some labels used in Jenkins Jira dashboard and filters, e.g. `jcasc-compatibility`, `java11-compatibility`, `jep-200`, etc. Assigning such labels helps users and maintainers to discover issues and act on them. There is no list of such "common labels" recommended for use. Some labels can be found in similar issues or documentation linked from system log entries in the reports. * **Move security issue** to the `SECURITY` project. Sometimes the issue reporters do not follow the link:https://www.jenkins.io/security/#reporting-vulnerabilities[vulnerability reporting] process and report security issues in public. If you see such issues, move them to the `SECURITY` project so that the security team takes care of their triage. Note that the required fields are different between projects, so some manual updates might be required when moving them. * **Label regressions and CC stakeholders** if an issue is reported as a regression with a clear root cause, please set a `regression` label and, if applicable, CC contributors of a change that led to the regression. * **Resolve invalid issues and support requests**. Sometimes Jenkins Jira is used as a support portal. We do not want to encourage that. Jenkins Jira is an issue tracker, and we expect reporters to investigate issues on their side to an extent that they can be reviewed by maintainers. For support requests, users are expected to use the link:https://community.jenkins.io/c/using-jenkins/support/8[community forum], link:https://www.jenkins.io/mailing-lists[mailing lists], link:https://www.jenkins.io/chat/[chats] and other resources (e.g. Stackoverflow). It is fine to link users to link:https://github.com/jenkinsci/.github/blob/master/SUPPORT.md[this page]. * **Resolve duplicates**. It is often that the same issue is already reported in the Jenkins database. Newly reported duplicates can be just resolved with a `Duplicate` resolution and linked to the original issue. === HOWTO: Triage by maintainers Further triage focuses on confirming the issue and defining a potential resolution. It can be performed by _Issue Triage Team Members_ if they want to dive deeper, or they can leave it to component maintainers. Triage objectives: * **Confirm reported defects**. Try to reproduce the issue or analyze the codebase. If the issue is legitimate, it is great to explicitly confirm it in a comment. * Nice2Have: **Define the next steps**. If possible, define a potential resolution for the issue. If you do not plan to work on the issue in foreseeable future, it is great to explicitly highlight that by unassigning the issue and inviting the reporter and other contributors to submit a fix. * Nice2Have: **Highlight newcomer-friendly issues**. Newcomer-friendly issues are instrumental for an onboarding new code contributors to the project. They are linked from the link:https://www.jenkins.io/participate/code/[contributing guidelines]. If you see a simple issue but do not plan to work on it, put a `newbie-friendly` label on it so that somebody could pick it up. === How to scrub issues? In addition to the initial triage, it is a good practice to sometimes review previously reported issues so that we could minimize the backlog of issues and simplify search by users. * **Triage reopened issues**. Same as for newly reported issues, it is great to process reopened issues if they are not acted on by the issue assignees. Often such issues can be resolved with a request to report a new issue if an issue is reopened due to another issue. * **Resolve stale untriaged issues**. Issue reporters may become unresponsive before their issue can be fully triaged. If there is a reported issue that does not contain data for reproducing the issue, it is fine to resolve them after a 2-week timeout with the `Incomplete` or `Cannot reproduce` resolution. * **Resolve/update obsolete issues**. Sometimes issues become obsolete due to other changes in the Jenkins core (e.g. feature removal), and such issues can be closed. Same for detaching functionality from the Jenkins core and plugins, issues can be reassigned to the new Jira component so that they are removed from the core backlog. === Triaging requests for enhancement Requests for enhancement (RFEs) include the `New Feature` and `Improvement` types in Jenkins Jira. The process to triage them might be different from bug reports. because it is not always possible to say whether a request should be implemented in the Jenkins core, an existing or a new plugin. In the case of doubt, it is fine to just skip an issue or CC subject matter experts who could advise. For RFEs which are not related to the Jenkins core or plugins, it is possible to set the `plugin-proposals` component. Note that this component is not regularly scrubbed, and it can be considered only as a pool of ideas somebody could implement. It is a good practice to set expectations in a comment when updating the RFE. === Responding to pings in triaged issues Some submitters and users tend to ping triage contributors to ask about the fix ETA. In some cases, they may also assign the issue and keep pinging. It is fine to not answer these questions on such pings and to refer requestors to this document, triage team members are not responsible for handling the ticket after initial triage. Other materials which might help: * link:https://www.jenkins.io/participate/code/[Contribute to Jenkins / Code] or link:https://github.com/jenkinsci/jenkins/blob/master/CONTRIBUTING.md[Contributing to the Jenkins Core] - extended version of "feel free to contribute". * link:https://github.com/jenkinsci/.github/blob/master/SUPPORT.md[Jenkins Support Disclaimer Page] - for those requesters who expect quick response and SLA. * link:https://www.jenkins.io/doc/developer/plugin-governance/adopt-a-plugin/[Plugin Adoption Policy] - for pings in not actively maintained components. * link:https://www.jenkins.io/project/conduct/[Jenkins Code of Conduct] - when it gets ugly. === Resolving vs. Closing issues Jira workflow for the `JENKINS` project has two similar states: `Resolved` and `Closed`. Historically the issues are rarely being **closed**, and all dashboard and Jenkins processes interpret resolved issues as closed. The main difference is that the _Resolved_ issues can be reopened by users while _Closed_ ones can be reopened by admins only. For triage purposes, it is recommended to use the `Resolved` state if there is a chance that the issue will be reopened by the reporter or other contributor (e.g. resolving due to inactivity, disagreement with the resolution, etc.). == Merge process === Common merge process ==== Step 1: Maintainer checklist Merge process can be initiated once a pull request matches the requirements: * Pull request is compliant with requirements to submitters (see the link:/.github/PULL_REQUEST_TEMPLATE.md[pull request template]) * There are at least 2 approvals for the pull request and no outstanding requests for change * Conversations in the pull request are over OR it is explicit that a reviewer does not block the change (often indicated by line comments attached to an approving PR review, or by using the term "nit", from "nit-picking") * Changelog entries in the PR title and/or _Proposed changelog entries_ are correct and reflect the current, final state of the PR * Proper changelog labels are set so that the changelog can be generated automatically. A List of labels we use for changelog generation is available link:https://github.com/jenkinsci/.github/blob/master/.github/release-drafter.yml[here]. * If the change needs administrators to be aware of it when upgrading, the `upgrade-guide-needed` label is present and there is a `Proposed upgrade guidelines` section in the PR title (link:https://github.com/jenkinsci/jenkins/pull/4387[example]). This is usually the case when a data migration occurs, a feature has been removed, a significant behavior change is introduced (including when there is a way to opt-out), or in general when we expect at least a large minority of admins to benefit from knowing about the change, e.g. to apply a new option. * If it would make sense to backport the change to LTS, a Jira issue must exist, be a _Bug_ or _Improvement_, and be labelled as `lts-candidate` to be considered (see link:https://issues.jenkins.io/issues/?filter=12146[this Jira query]). ==== Step 2: Is it a good time to merge? link:https://www.jenkins.io/security/[Jenkins security updates] are coordinated with the LTS calendar. If the weekly release before an LTS release introduces regressions, users of the weekly line may have to choose between security fixes and a working Jenkins. The Jenkins security team will usually send a "pre-announcement" to link:https://groups.google.com/forum/#!forum/jenkinsci-advisories[the advisories list] on Wednesday or Thursday the week before release, but that's not always doable. For these reasons, the following changes should not be merged during the week before LTS releases (weeks 3, 7, 11, 15, etc. on the page linked above): * Changes that could be considered risky (relatively high risk of introducing regressions), as they could make users of Jenkins weekly releases choose between getting security fixes, and having a functioning Jenkins * Very large changes (in terms of lines changed), because the Jenkins security team needs to prepare security fixes for the weekly release line in a very short period of time. If the change is ready, but it is not a good time, consider labelling the pull request with the `on-hold` label. Make sure to add a comment explaining why it was put on hold. ==== Step 3: Acceptance Once the checklist is passed, the PR is eligible to begin xref:acceptance[the acceptance process]. After that, the change will be landed in the next weekly release. LTS backporting, if needed, will be handled separately by the release team. === Exceptions * Jenkins Security Team uses a different process for security issue fixes. They are reviewed and integrated by the Security team in private repositories. Security hardening and enhancements go through the standard process. * Release Team members are permitted to bypass the review/merge process if and only if a change is needed to unblock the security release. Common review process is used otherwise. * Only one approval is required for low-risk small changes with the `skip-changelog` label, as long as both author and approver have write access to the repository. Note that the 24-hour waiting period still applies. * 24 hours waiting period after adding the `ready-for-merge` label is not required for: //TODO(oleg_nenashev): Define "trivial" better to avoid loopholes ** changes that do not result in changes to the primary functionality, such as typo fixes in documentation or localization files ** changes that do not affect the production code: Jenkinsfile tweaks, tools inside the repo, etc. ** broken master build === Squashing pull requests OR not? Sometimes we have pull requests which include dozens of commits including many non-substantial changes (merge commits, addressing review comments, etc.). We do not require contributors to spend time on cleaning it up, because core maintainers can squash PRs during the merge. Reviewers can add a link:https://github.com/jenkinsci/jenkins/pulls?q=is%3Aopen+is%3Apr+label%3Asquash-merge-me[squash-merge-me] label during reviews to highlight that it is needed. At the same time, we do not require any pull request to be merged as a single commit. Multiple commits are useful in many cases. When do we merge pull requests as is? * There is only one commit with a reasonable commit message * There are multiple atomic commits. Each commit has a reasonable message and can be compiled on its own ** Example: *** **Commit 1**: `[JENKINS-1234] - Reproduce the issue in tests` *** **Commit 2**: `[JENKINS-1234] - Fix the issue by updating Foo` * There are multiple commit authors who expressed the desire to keep commit history as is. By default, we do not consider multiple authors as a blocker for squash, because GitHub now link:https://help.github.com/en/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors[supports co-authors] When do we squash commits? * We squash commits when core maintainers decide to do so (`squash-merge-me` label), usually when the conditions above are not met. * There is no strong requirement to squash merge pull requests at the moment, so there might be deviations from the merge policy in practice. == Release process === Weekly release process link:https://www.jenkins.io/download/weekly/[Jenkins Weekly releases] are managed by the Jenkins Release Team which has access to the dedicated release environment within the Jenkins Infrastructure. References: * link:https://www.jenkins.io/download/weekly/[Jenkins Weekly Releases Documentation] * link:https://github.com/jenkins-infra/release[Jenkins Release Environment and the release process] * link:https://github.com/jenkinsci/packaging[Native Jenkins packages and installers for platforms] * link:https://github.com/jenkinsci/docker[Docker packaging for Jenkins] === LTS Process Jenkins also offers the link:https://www.jenkins.io/download/lts/[LTS Release Line]. It is maintained by the Jenkins Release Team which coordinates link:https://www.jenkins.io/download/lts/#backporting-process[backporting] and release candidate testing. Any Jenkins contributors are welcome to participate in backporting and release candidate testing. * Backporting discussions happen through the developer mailing list. * Backports are submitted as pull requests with the link:https://github.com/jenkinsci/jenkins/labels/into-lts[into-lts] label. * Release candidate testing is announced on the developer mailing list. Discovered issues should be submitted to Jenkins Jira and then referenced in the release candidate testing thread. == Tools * link:https://issues.jenkins.io/secure/Dashboard.jspa?selectPageId=20340[Core maintainers board] - Lists unresolved recent regressions, unresolved recent core bugs, and popular new issues. * link:https://github.com/jenkinsci/core-pr-tester[Core Pull Request Tester] * link:https://github.com/jenkinsci/core-changelog-generator[Core Changelog Generator] * link:https://github.com/jenkins-infra/release/tree/master/tools[Toolkit for LTS backporting] * link:/update-since-todo.py[@since version updater] == Feedback The process documented in this document is not set in stone. If you see any issues or want to suggest improvements, just submit a pull request or contact us in the communication channels referenced above. Any feedback will be appreciated!