Skip to content

Latest commit

 

History

History
67 lines (48 loc) · 4.09 KB

_STYLEGUIDE.adoc

File metadata and controls

67 lines (48 loc) · 4.09 KB
Raw

Jenkins Changelog Styleguide

The Changelog describes notable changes in Jenkins. Not all changes are included, but all changes impacting users or developers are.

Types of changes

The changelog supports five different types of changes:

  • security refers specifically to security fixes. These changes are typically just references to a security advisory.

  • major bug are major bug fixes. bug are all other bug fixes.

  • major rfe are major new features and improvements. rfe are all other features and improvements.

Library upgrades are generally assigned the label matching the motivation for the upgrade, which should be reflected in the label: Upgraded foo from 1.2 to 1.4 to fix problems related to widget frobnication.

When in doubt about the nature of a change, a change should be marked as an RFE and not a bug fix.

Use the major label for changes that are very important, or have a high risk of introducing regressions (which often corresponds to the number of lines changed).

Labels

  • Describe the change in the imperative mood, present tense, and second person; e.g., write "fix a problem" rather than "fixes a problem" or "fixed a problem". Descriptions of previous (now obsolete) behavior can deviate from this rule.

  • Use the "Developer:" prefix for any changes expected to only matter to developers of core or plugins.

  • Use the "Internal:" prefix for any notable internal changes with no expected impact outside core.

  • When upgrading a library or similar dependency included in Jenkins, include both the former and current version number.

  • Use complete sentences as label, and end them with a period.

    • Changelog entries related to security fixes are an exception to this, as they only state Security fixes or Important security fixes. Use the latter label in case any fixes are considered high or critical severity.

Messages

Up to one highlighted message can be assigned to a Jenkins release. Reserve these messages for important announcements that go beyond regular changes. Examples include new required minimum Java versions, introduction of a system like JEP-200 with expected widespread impact, or when a release is very broken (e.g. improperly released, does not include notable changes, very severe regression requiring an emergency followup release).

Order of entries (regular)

We generally order entries in descending order of importance.

  • Group entries by type ('major rfe' and 'rfe' are different types, the same applies to bugs). An exception to this are entries that are only relevant to developers, or are considered 'internal' (no expected user impact). Those are always listed last.

  • Put 'major' changes before non-major changes.

  • Always put 'security' entries first, if any.

  • After any 'security' entries, put the most important non-security change in the release. This is typically a 'major rfe' or 'major bug', if any.

  • If in doubt, alternate rfe and bug entries to use the contrasting color to visually separate groups of entries.

Order of entries (LTS.1 changelog)

The changelog for the first LTS release of a new LTS line contains a section for notable changes since the previous LTS release. These generally follow the priority order outlined above, but for improved readability, related changes (e.g. all changes related to various remoting updates) should be grouped. See past changelogs for an example of grouping of related issues. When several issues combine to form a more significant capability, related entries may be merged into a single entry. Likewise, when a series of pull requests have updated the same component, those entries may be merged into a single entry. Merging related entries into a single entry may justify assigning "major rfe" to the grouping even if none of the individual entries were a "major rfe".

Minor changes

Some changes are too minor to note in the changelog. These include small-scale localization updates, Javadoc updates, some annotation updates.

These don’t get changelog entries as to not make the changelog too busy. Instead comments in the YAML changelog file note these changes, and explain why they aren’t visibly included.