{"id":18937540,"url":"https://github.com/rollerworks/release-management-guidebook","last_synced_at":"2026-02-10T21:05:37.977Z","repository":{"id":147995108,"uuid":"74559948","full_name":"rollerworks/Release-Management-GuideBook","owner":"rollerworks","description":"📖 The Release Management GuideBook contains a set of rules and guidelines for managing software releases.","archived":false,"fork":false,"pushed_at":"2016-11-24T13:32:45.000Z","size":13,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-31T21:42:25.784Z","etag":null,"topics":["guides","keepachangelog","maintenance","management"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rollerworks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-23T09:13:24.000Z","updated_at":"2024-02-13T23:51:59.000Z","dependencies_parsed_at":"2023-05-28T05:00:19.178Z","dependency_job_id":null,"html_url":"https://github.com/rollerworks/Release-Management-GuideBook","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rollerworks%2FRelease-Management-GuideBook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rollerworks%2FRelease-Management-GuideBook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rollerworks%2FRelease-Management-GuideBook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rollerworks%2FRelease-Management-GuideBook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rollerworks","download_url":"https://codeload.github.com/rollerworks/Release-Management-GuideBook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239937700,"owners_count":19721483,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["guides","keepachangelog","maintenance","management"],"created_at":"2024-11-08T12:11:36.783Z","updated_at":"2026-02-10T21:05:32.945Z","avatar_url":"https://github.com/rollerworks.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"Release Management GuideBook\n============================\n\nThe Release Management GuideBook (Release Management for short)\ncontains a set of rules and guidelines for managing software releases.\n\nThis guide can be used for both libraries and complete applications.\nIt's designed mainly for open-source/free software but can also be used\nfor closed (or proprietary) software.\n\n## Rules\n\nThese listed rules are to be followed strictly, without exception.\n\n* Information about the release and steps for upgrading to a new release\n  must be provided in a human readable format (eg. Markdown or rest-doc).\n* Use [Semantic versioning] for versing numbering and public API stability.\n* Write stability `ALPHA,BETA,RC` always in uppercase, and full (not a or b.)\n* Omit `STABLE` within the release name and version number.\n* Keep a changelog as described in [keepachangelog.com] - \n  (and see additional notes below).\n* Don't increase Platform requirements within minor/patch release,\n  unless this requirement is widely available.\n* Keep upgrade instructions in `UPGRADE.md` (or `UPGRADE-x.y.md` when the file\n  becomes to big otherwise). And see additional notes below.\n* Include `[SECURITY RELEASE]` when the release contains security patches\n  Eg. `Release v1.0.0-BETA2 [SECURITY RELEASE]`.\n* Update the release title of broken release with `[YANKED]`.\n  Eg. `Release v1.0.0-BETA2 [YANKED]`.\n* Suffix (full) version numbers always with `v` (in lowercase).\n  Eg. `v1.0.0-BETA1`, `v1.0.0` (see notes below).\n\n[Semantic versioning]: http://semver.org/\n[keepachangelog.com]: http://keepachangelog.com/en/0.3.0/\n\n### Broken releases\n\nA release is considered broken when it's impossible to it use at all\nor when meta-data is wrong (eg. forgot to update the version number).\n\nA broken release must be followed-up with a new release.\n**Don't reuse the old version number!**\n\nA broken release includes (but is not limited to):\n\n* Syntax/linting errors.\n* The bundled Installer is broken.\n* Forgot to remove temporary debugging information.\n* Versioning information in the code was not updated.\n  or wrongfully changed.\n* Violation of the BC promise\n  (eg. bumped platform requirements before major release).\n* Security bug introduced (by locked dependency).\n\n### Versioning prefix\n\nAll (full) version numbers must always be prefixed with `v` (in lowercase).\nEg. `v1.0.0-BETA1`, `v1.0.0`.\n\nThere is some discussion about using, or omitting the `v` prefix.\nFor all clarity this section was included.\n\nThe maintainers of the Git project recommend to always prefix version numbers\nwith `v` (for Git tags) to make it explicit it's a version number.\nAnd to prevent confusion with branch-names.\n\nSome developers however advise to omit the prefix, as it's redundant,\nbut this number of users is decreasing.\n\nSo for all feature releases, the version number must be prefixed with\na lowercase `v`.\n\n## Upgrade format\n\nTBD.\n\n* Was/becomes examples\n* Use FQCN only once per section to save on excessive text block\n\n## Changelog format\n\nUse format as described in [keepachangelog.com].\n\nKeep changelog per major version, or minor (when the file\nbecomes to big otherwise).\n\n*It's advised (but not required) to use a software tool to generate\nthe changelog. Maintainers can use [HubKit] to generate a changelog.*\n\n**Note:** The `Security` group MUST be placed first,\nso users cannot mis important security fixes.\n\n## Guidelines\n\nThe following set is recommended but not mandatory, project maintainers\nare advised to follow them, or define there own set or rules.\n\n### Plan ahead\n\nA good release is planned, contains only that what was envisioned.\nAnd is delivered on time. Don't be afraid to reject features for the next\nrelease when they are not good enough yet.\n\nBe watchful for big releases, the more changes the greater the chance\nsomething is broken. As with software development itself: don't do anything\nmore then what is needed to get the job done.\n\n### Release often\n\nRelease as often as possible, don't wait endlessly with a new release.\nA good roadmap and planning will help to streamline this and prevent\nbroken releases.\n\n*It's better to have an early beta release with missing functionality\nthen a stable release with half working functionality.*\n\nEven when development is still going on and not everything is stable\nyet, it will help early adapters to start testing and lock to a specific\nversion without the risk of pulling-in new changes.\n\n*A release is more then a presentation of features, it's a promise to\nusers that nothing changes for this release (it's written in stone).*\n\nWhen support for older minor versions is provided, make a new patch release,\nat least once a month. Eg. at the end or start of the month.\nUsers now have an indication when a fix for a bug is available,\nwithout having to update every day/week or waiting for to long.\n\n**Note:** Proper automated tests and continues integration ensures\na release is functional. Delaying a patch release because you are\nnot sure it's stable enough is the indication of a bigger problem.\n\n### Maintenance period\n\nA release must be maintained for a period of time, that is\nthe maintainers provide and accept patches to fix problems.\nAnd make new patch releases.\n\nHow long this maintenance period is, heavily dependents on your team size,\ncomplexity of the software and actual usage of older versions.\n\n**Note:**\n\n\u003e Any old version you maintain is a burden, it's a choice\n\u003e wether you \"can\" provide support for these older versions.\n\u003e Don't feel bad when you can't maintain all versions.\n\nMaintenance is divided into two types: minor and major.\n\n* A Minor release is usually maintained until the next Minor release\n  or 6 months for bug fixes and at least 1 year in total for security fixes.\n* A Major release is usually supported for 18 months or two 2 years\n  for bug fixes, plus an additional 6 months for security fixes.\n\n  When possible paid, extended support may be provided for commercial users.\n  This is however mandatory.\n\n**Caution:** Don't make the maintenance period for security fixes to short,\nas this risks leaving users vulnerable to attacks. 6 months minimum should\nbe enough.\n\n## Stability\n\nEach release follows a clear path of stability. Maintainers should not ignore\nthis path as it will make things harder when an unexpected changes are required.\n\n* `ALPHA` indicates that work is still going on,\n  things may be broken or undecided. Only for developers.\n* `BETA` is usable for testing and early adapters, some features\n  may be removed when they remain unstable.\n* `RC` is for bug fixes only, no new features can be introduced\n  unless required to fix a Security problem.\n\n## Major release type\n\nThere three distinct major release types, with a clear stability\npath to follow. The time period of this path is undefined, any release\nmay follow shortly after the previous one, but should have at least one\nday in between.\n\nA Stability between `[]` is considered optional and can be skipped\nwhen development is stable enough.\n\n### Pre-1.0\n\nThis is the initial development phase, no (API) stability\nshould be expected at this point. This provides for receiving\nearly feedback and allows for experimentation.\n\nTo prevent delays in development, the support cycle for minor releases\nshould be short (no more then 2 months or 2 minor releases a time),\nor support for older versions can be omitted completely.\n\nStability path: ALPHA -\u003e BETA -\u003e RC -\u003e STABLE.\n\n* Make a minor release directly after the completion of any (planned)\n  refactoring (with BC breaks), don't delay.\n* Don't break the API between patch releases, use patch releases only\n  for bug fixes.\n* Use `0.x` instead of `1.0.0-ALPHA1`\n\n### Transitional release\n\nThis is the preferred major release type, it provides a smooth\ntransition for the users and implementors.\n\nThe (last) minor version of the current Major contains a list of\ndeprecations, that will be removed in \"this\" new Major release.\n\nOnce the user has taken care of all deprecations (warnings), and\nupgraded to the new API it's possible to switch to the new version\nby simply installing the new version.\n\nStability path: BETA -\u003e [RC] -\u003e STABLE.\n\nThe RC stability can be skipped, but this should be carefully considered\nfor each release plan.\n\n### Refactor release\n\nThis is a more radical release plan as no smooth transition\nis provided for the users and implementors.\n\nIt should only be used to solve problems that cannot be done cleanly by\ndeprecating first. This may include switching to a Platform version\n(which requires syntax changes) or upgrades of dependencies that\ncannot be provided with an BC adapter.\n\nStability path: ALPHA -\u003e BETA -\u003e RC -\u003e STABLE.\n\nThe number of this release type should be limited, eg.\nshould have at least 2 stable major releases in between.\n\n## Credits\n\nCreated by [Sebastiaan Stok](https://github.com/sstok) provided under the\nterms of [Creative Commons Attribution Non Commercial Share Alike 3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/legalcode)\n\n:heart: Contributions are welcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frollerworks%2Frelease-management-guidebook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frollerworks%2Frelease-management-guidebook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frollerworks%2Frelease-management-guidebook/lists"}