Release notes and semantic versioning

[jhomarolo]

I believe that with the growth of the library, we need to implement better control of release notes and also control of versions released X.X.X (ex: when a version goes from 1.0.10 to 1.1.0 instead of 1.0.11)

There is a convention for that and I believe we could follow it: https://semver.org/

Motivators for release notes:

• Follow semantic versioning in order to reflect project changes to consumers and differentiate between features releases, bug fixes and breaking changes.
• Generate release notes/changelog so that other developers using your library can understand what exactly are the changes included in every release and their implications.
• Communicate changes to clients and/or project managers.
• Make releases part of your continuous integration system.
• The process of manually generating releases, bumping versions and creating release notes can be painful, error prone and emotional.
• Automatically create a git tag and publish the new version of your library on npm.

Some tutorials about it: https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository

[dalssoft]

Totally agree. We could start with the central libs (buchu, gotu e suma) that are more mature.

[jhomarolo]

I found this here, I believe it explains how we should follow: https://github.com/semantic-release/semantic-release

• Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.

• Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.

• Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards-compatible manner, and
• PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

About the commit messages indicating wich type of version it is. Here is an example of the release type that will be done based on a commit messages:

Commit message	Release type
fix(pencil): stop graphite breaking when too much pressure applied	Patch Release
feat(pencil): add 'graphiteWidth' option	Minor Feature Release
perf(pencil): remove graphiteWidth optionBREAKING CHANGE: The graphiteWidth option has been removed.The default graphite width of 10mm is always used for performance reasons.	Major Breaking Release

Here is a good article, about this: https://itnext.io/automate-your-releases-versioning-and-release-notes-with-semantic-release-d5575b73d986

[jhomarolo]

Hi guys, just updating you guys on version control and I've made some advances, but I'd like to hear from you guys on that.

I am using https://github.com/semantic-release/semantic-release as a tool for this feature and I would like to point out a few things.

Strengths:

• It automatically creates new versions according to the commit semantics. He knows when it's just a patch, or a minor release, or a major release.

• It already creates a changelog automatically based on the commit history, including dates, building a very nice timeline (https://github.com/jhomarolo/buchu/blob/master/CHANGELOG.md)

• It already creates a new release with tags in git and github. (https://github.com/jhomarolo/buchu/releases)

• It has integration with npm, that is, it can automatically generate and launch a new version for us

• It has integration with github actions

Negative points:

• It uses a Google team-based commit message semantics (https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines), if you don't use this semantica, it does not detect new versions.

• You don't have control of the version you are releasing, it's always generated based on the commit messages, but you can decide when to release a new version. Examples:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

• The setup is a little complex, as there is a great possibility of configurations, it will take a little work to put in all libs.

• We will have to "restart" counting all libs, to 1.0.0, but this goes with what we wanted when migrating the library under the herbs organization (Move all npm packages to a organization scoped package #12)

I'm waiting for your feedback

[thgpdr]

It's a nice approach, and the market standard.

semantic-release is the way to go

[BritoDoug]

Wow, what amount of info did you have @jhomarolo, great job.
About semantic-release:

• The Strengths are really good and make total sense to me
• About the bad points, I dont have a problem in use Google team-based commit, if everyone agree. And how much work/time did you think we need to run semantic-release in a repo ?

anyway, I agree to adopt that solution

[jhomarolo]

Thanks @BritoDoug and @thgpdr for feedback.

@dalssoft , @maikmb, @italojs what do you think about this approach?

[maikmb]

Hi @jhomarolo , it make sense for me! HerbsJs are growing and we must keep better version control.

[jhomarolo]

I'll proceed with this implementation.

[jhomarolo]

First package with semanct versioning: https://github.com/herbsjs/herbs

[jhomarolo]

All the libraries now uses seemantic release and commitizen to :

• generate changelog
• control version
• publish to npm via github actions

It's important to say that now we must use this format for commit messages (https://semver.org/). To help with this task I've implemented the commitizen to all libraries, just follow those steps:

1. npm install -g commitizen
2. write a lot of good code to contribute to herbs 🌿
3. git add .
4. ( git cz or npm run commit or npx cz ) instead git commit
5. git push

We also restarted the version of all libraries since we moved to herbsjs organization #14

🚀

[dalssoft]

this info should be on every README so a contributor knows how to do it