Working in the past with different frameworks and libraries we experienced it was to a certain degree easy to integrate into projects. In most cases it was much more difficult to keep the dependencies updated properly compared to introducing them. This is something we want to be different. In our fast-paced world of changes we need to also look out for these qualities.
The changelog file in the root of the package has a preface for the rules inside the changelog file. We follow the format of the keep a changelog project with semantic versioning which formats the file in a standardized layout.
For every version we will have changes listed. It is allowed to release a package without a change to properly release a group of interdependent packages so an empty section is fine. There is always a version entry called
Unreleased to collect new entries up to the release of the upcoming version.
The logs of each version are grouped into their classification of additions, changes, deprecations, removals, fixes and security fixes. To ensure a better understanding of the change the logs are focussed on features of the package written in present tense. Each log has to contain a technical reference to look up usages of the feature.
Depending on the change we can form scenarios into changelogs. When you are unsure what to write you can find some sample texts below:
Extract code of private API into code of public API
This introduces a feature, so we should write something like:
- Introduce fiddling of stuff into new class `\Heptacom\HeptaConnect\StuffFiddler`
As seen in version 0.8.0 of heptaconnect-core:
- Extract path building from
\Heptacom\HeptaConnect\Core\Storage\Normalizer\StreamDenormalizerinto new service
Add parameter to method of public API
This introduces new behaviours, so we also add a new feature:
- Add optional parameter `$foobar` in `\Heptacom\HeptaConnect\StuffFiddler::fiddle`
As seen in version 0.7.0 of heptaconnect-core:
- Add parameter for
When you have a generic component, that is not well optimized for certain cases, can be replaced with a new more optimized component:
- Add class `\Heptacom\HeptaConnect\GizmoStuffFiddler` that can fiddle better with stuff of gizmos in terms of memory handling
- Remove `\Heptacom\HeptaConnect\StuffFiddler::fiddle`. Use `\Heptacom\HeptaConnect\GizmoStuffFiddler::fiddleGizmos` instead
As seen in version 0.8.0 of heptaconnect-storage-base:
- With storage restructure explained in this ADR we add
\Heptacom\HeptaConnect\Storage\Base\Contract\Action\Route\Get\RouteGetActionInterfacefor reading metadata of routes by the given
\Heptacom\HeptaConnect\Storage\Base\Contract\Action\Route\Get\RouteGetCriteriato return a
- With storage restructure explained in this ADR we remove implementation
\Heptacom\HeptaConnect\Storage\Base\Contract\Repository\RouteRepositoryContract::readin favour of
\Heptacom\HeptaConnect\Storage\Base\Contract\Action\Route\Get\RouteGetActionInterface::getthat allows for optimizations in the storage implementation
Upgrade composer dependency
Pre-checking composer upgrades is important to reveal changes of further application fine-tuning, so we mention them as well:
- Upgrade composer dependency `psr/log: ^1.0` to support future versions `psr/log: ^2.0`
Fix a bug
The difficult part here is the differentiation between a security bugfix and an unexpected behaviour:
- When passing foobaz into `\Heptacom\HeptaConnect\StuffFiddler::fiddle` did not pay respect to a GizmoStuff situation
As seen in version 0.7.0 of heptaconnect-portal-base:
\Heptacom\HeptaConnect\Portal\Base\Support\Contract\DeepObjectIteratorContract::iteratedrops usage of
\spl_object_hashto not break on garbage collection
Add unique log code for lookups
When anything is logged or an exception is thrown a package-unique code should be generated. Using a UNIX timestamp is handy as it is an integer and plays nicely with
\Throwable::getCode. These have to be documented in the changelogs as well to raise awareness and be the first contact point for persons in need of an explanation.
- Add log exception code `123456789` to `\Heptacom\HeptaConnect\StuffFiddler::fiddle` when fiddling with stuff that is not allowed to access gizmos
As seen in version 0.8.0 of heptaconnect-core:
- Add log exception code
\Heptacom\HeptaConnect\Core\Job\Handler\ReceptionHandler::triggerReceptionwhen job has no related route
Rename classes or move classes between namespaces
When a code refactoring needs moving a class a plain
move hint should to be added to the changelog. Additional explanation is optional but suggested as most refactoring have a good reasoning regarding functionality.
- Rename `\Heptacom\HeptaConnect\StuffFiddler` to `\Heptacom\HeptaConnect\StuffFiddlerHandler`
As seen in version 0.5.0 of heptaconnect-dataset-base: