diff options
| -rw-r--r-- | docs/how-to-use-changelog.md | 74 | ||||
| -rw-r--r-- | docs/project-versioning.md | 41 |
2 files changed, 97 insertions, 18 deletions
diff --git a/docs/how-to-use-changelog.md b/docs/how-to-use-changelog.md new file mode 100644 index 0000000..4094ba3 --- /dev/null +++ b/docs/how-to-use-changelog.md @@ -0,0 +1,74 @@ +# How to use changelog + +All breaking/notable changes to this project will be documented in the `/docs/changelog/master.md` file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](project-versioning.md). + +**This changelog should provide an easy way for the developers to upgrade their own code which is connected to AzerothCore** (e.g. modules, APIs, scripts etc.) +It's not a way to keep track of ALL the changes made (we have the git history for that). Therefore, just 2 golden rules to follow: + +- **DO WRITE** changelog when you added breaking changes, security fixes or important new features that other people can use. +- **DO NOT WRITE** changelog when you are adding small fixes or minor improvements. + +## How to create a changelog + +The creation of a changelog for a PR is similar to the creation of a new sql file. +Under the `doc/changelog/pendings` folder you will find a `create.sh` script. + +Run this script to create a new changelog file in the same folder which will be automatically called `changes_<timestamp>.md`. + +Once the PR is merged, our pipeline will merge your file into the `doc/changelog/master.md` by automatically creating a new section inside that file. +This section will be titled with the new version number based on the previous one from the `acore.json` file you can find within the root folder. + +So, for instance: + +if the current version is `1.0.0-dev.1`, after your PR is merged it will be changed to `1.0.0-dev.2` automatically within the `acore.json` and a new section +called `## 1.0.0-dev.2` will be created under the `master.md` changelog. + +This approach is pretty useful also for modules to keep track of the compatibility + +## How to write a changelog + +It's mandatory to use the "[Keep a Changelog](https://keepachangelog.com/en/1.0.0/)" format, by correctly using the following types of section titles: + +- Added for new features. +- Changed for changes in existing functionality. +- Deprecated for soon-to-be removed features. +- Removed for now removed features. +- Security in case of vulnerabilities. + +You have to create a new H3 section ( `###` in markdown) for every different type of changes. + +For example: + +``` +### Added + +- new hooks X, Y +- new formula for Z + +### Changed + +- return value for hook X, now it's boolean instead of void +``` + +### Document how to upgrade + +After the sections above you have to describe the steps needed to upgrade the code. This is the **most important part** and it's particulary useful for module authors to fix their code based on what you changed without struggling reading tons of commits and looking for information around. + +To do so, you can use the generated ```### How to upgrade``` section by our `create.sh`. +Please, be as much as detailed as possible. +If the guidelines are very long and they require more than few lines (an entire wiki page for instance), you can just link that page then. + +Example: + +``` +### How to upgrade + +- The hook OnCheck of the Achievement script class now returns a boolean instead of a void. Add `return true` to your methods if you don't want to change the original behaviour. +``` + +## How to release a new major version + +This is a manual process. Everytime we release a new major version (4.0.0, 5.0.0 etc.) we need to move the `master.md` into the `doc/changelog/previous-versions` folder and rename it using this format: `v[major].x.md`. After that we have to create a new empty `master.md` file diff --git a/docs/project-versioning.md b/docs/project-versioning.md index e931514..9099415 100644 --- a/docs/project-versioning.md +++ b/docs/project-versioning.md @@ -2,50 +2,55 @@ redirect_from: "/Project-Versioning" --- -# Project Versioning +## Project Versioning We are using the semantic versioning standard: http://semver.org/spec/v2.0.0.html -For instance, we can have: **1.5.1** that corresponds to: **MAJOR.MINOR.PATCH** +For instance, we can have: **1.5.1-dev.1** that corresponds to: **MAJOR.MINOR.PATCH-PRERELEASE** More in depth: -**MAJOR** version when you make incompatible API / DB structure changes +* **MAJOR** version when you make incompatible API / DB structure changes. In AzerothCore we release a MAJOR version once in a while and we support only security fixes right after (read the section below). Therefore, this version can be seen more as a Milestone. -**MINOR** version when you add functionality in a backwards-compatible manner +* **MINOR** version when you add functionality in a backwards-compatible manner. This is mostly unused on AC since we do not import any new functionality after we release a MAJOR version. -**PATCH** version when you make backwards-compatible bug fixes. +* **PATCH** version when you make backwards-compatible bug and security fixes. -Additional labels for branches ( such as -rc , -dev etc. ) are available as extensions to the MAJOR.MINOR.PATCH format. +* **PRERELEASE** this is such called "metadata" in semver standard. We use this part of the versioning while we work on **master** branch. Everytime a new feature or breaking change (on both code or db) is released, this number is increased to notify you regarding possible actions to take. Check [how to use the changelog](how-to-use-changelog.md). -* **PHASE 1: Developing Phase**: During the developing phase, we will use the master branch where we can freely make changes to API, DB and all things that could break compatibility with old revisions. -At the beginning of each development phase, we will clean the sql/updates folders archiving old SQLs. +### PRERELEASE first - N.B. - * Some big jobs, such as rewriting/implementing features, could be not ready for next revision and eventually they will be planned for a future one, so they will be kept in dedicated branches instead of master. - * Using master branch you will have immediate access to new awesome features, but you must take care since some commits can break stability in some rare cases. +AzerothCore is not yet considered a "completed" software at an enterprise level. The versioning described above will be used to provide a simple way to check if a module, script or anything connected to AC is compatible or not with AC and what to do to upgrade it. -* **PHASE 2: Content fixes**: At start of this phase we will publish first <stable> release ( x.0.0 ) and we will: +Our strategy is (in order of most common actions): - 1) create a branch for it +- to not update the version when the changes are just fixes/chore changes +- to update the `-dev.x` prerelease version on master when we have breaking changes or new features +- to upgrade the major version when we decide to release a new stable version +- if any new security patch or feature is imported within the released major version, those ones will increase the minor/patch version then, but we do it very occasionally. - 2) export base db with updates included, but we will keep files in sql/updates to allow you easily upgrading from a previous release +## Dev stages - 3) create a downloadable github release and a dedicated wiki page for documentation. +* **PHASE 1: Developing Phase**: During the developing phase, we will use the master branch where we can freely make changes to API, DB and all things that could break compatibility with old revisions. +At the beginning of each development phase, we will clean the sql/updates folders archiving old SQLs. - During this phase we will continue to fix mechanics and contents without break compatibility with API, DB etc. + N.B. + * Some big jobs, such as rewriting/implementing features, could be not ready for next revision and eventually they will be planned for a future one, so they will be kept in dedicated branches instead of master. + * Using master branch you will have immediate access to new awesome features, but you must take care since some commits can break stability in some rare cases. -* **PHASE 3: Only Stability and security fixes**: In this phase we will stop to import mechanic / content fix and we will offer support to only security and stability issues. For example: if a function generates a crash for a null pointer, we will fix it. +* **PHASE 2: Only Stability and security fixes**: In this phase we will stop to import mechanic / content fix and we will offer support to only security and stability issues. For example: if a function generates a crash for a null pointer, we will fix it. We could eventually extends this phase if requested by many people. -* **PHASE 4: End of Life ( EOL )**: We will archive that release keeping documentation and branch ofc. You can continue to use/download it, but we won't offer any official support of any kind +* **PHASE 3: End of Life ( EOL )**: We will archive that release keeping documentation and branch ofc. You can continue to use/download it, but we won't offer any official support of any kind ## List of releases +NOTE: this is outdated, check our [releases](https://github.com/azerothcore/azerothcore-wotlk/releases) on github + | version/branch | codename | description | current state | release data | end of support| | -- | -- | -- | -- | -- | -- | | 0.x | Sunwell| small reworks for sunwell |EOL| 2016 Q3 | 2017 Q1 | |