hackergil commented 5 years ago

For each time we release on github, we need to include a change log that lists the changes that belong to the release. Here's an example:

https://github.com/angular/angular-cli/releases

And here's the angular script that generates it:

https://github.com/angular/angular-cli/blob/master/scripts/changelog.ts

tobi-or-not-tobi commented 5 years ago

I believe this requires some conventions to be followed in our commits, correct?

Xymmer commented 5 years ago

Tobias adds:

See https://github.com/angular/angular/blob/master/CHANGELOG.md for an example CHANGELOG.md


<a name="7.1.0-rc.0"></a>
# [7.1.0-rc.0](https://github.com/angular/angular/compare/7.1.0-beta.2...7.1.0-rc.0) (2018-11-14) Show more…
angular/angular

Angular-cli does it differently: https://github.com/angular/angular-cli/releases

Xymmer commented 5 years ago

Let's raise the priority of this so we get a changelog soon for the release of Nov 14 2018.

hackergil commented 5 years ago

Is this ready for review?

It needs some dependencies (conventional-commits-parser and others)
Code needs to be linted and prettified
We need documentation on how to run it (which you just stated it's in progress)

marlass commented 5 years ago

Proposal for version control conventions (based on angular convention):

Version control convention

Merge guidelines

Merge all pull requests using "Squash and merge" feature in github. Follow the commit convention when merging to develop.

Commit Message Guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the framework change log.

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and the scope of the header is optional.

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

The footer should contain a closing reference to an issue if any.

Samples: (even more samples)

ci: update travis configuration for new node version

fix(@spartacus/core): need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.

Revert

If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Type

Must be one of the following:

build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
docs: Documentation only changes
feat: A new feature
fix: A bug fix
perf: A code change that improves performance
refactor: A code change that neither fixes a bug nor adds a feature
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
test: Adding missing tests or correcting existing tests

In changelog we only present commits with type feat and fix. We might extend it later for example with style and perf.

Scope

The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages.

The following is the list of supported scopes:

@spartacus/core
@spartacus/styles
@spartacus/storefront

There are currently a few exceptions to the "use package name" rule:

none/empty string: useful for style, test and refactor changes that are done across all packages (e.g. style: add missing semicolons) and for docs changes that are not related to a specific package (e.g. docs: fix typo in tutorial).

Subject

The subject contains a succinct description of the change:

use the imperative, present tense: "change" not "changed" nor "changes"
don't capitalize the first letter
no dot (.) at the end

Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

Footer

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

marlass commented 5 years ago

Generating changelog instructions:

Generating changelog

Running script

To generate changelog run

yarn generate:changelog --from tag_from_which_to_check_commits(probably previous release) --to tag_to_latest_commit_in_release --githubToken personal_access_token_from_github

You can run it without --githubToken option with flag --verbose to print the changelog to console.

You can also replace --githubToken option with --tokenFile path_to_file_with_github_token if you run this command frequently.

If you miss some option script will inform you about it.

Release check

Script will generate draft of new release of our packages in repository releases. It should be then checked for any missing information/duplications. After this we can safely publish release.

marlass commented 5 years ago

I would also recommend to disable other merge options and allow only Squash and merge. It should help with adoption of new commit convention.

marlass commented 5 years ago

Dependencies added to package.json
tslint and prettier run on scripts directory
Docs in comments above. If we agree on commit message convention every team member should get familiar with it. We don't even need to follow the convention in each commit. Only squash commits will matter, but it would be good to use this in every commit for readability and consistency in project.

Let me know what you think. @hackergil

hackergil commented 5 years ago

Getting the following error when I run it: Error: Cannot find module 'conventional-commits-parser' at Function.Module._resolveFilename (internal/modules/cjs/loader.js:587:15) at Function.Module._load (internal/modules/cjs/loader.js:513:25) at Module.require (internal/modules/cjs/loader.js:643:17) at require (internal/modules/cjs/helpers.js:22:18) at Object. (/Users/i867028/git/github/spartacus/scripts/changelog.ts:16:35) at Module._compile (internal/modules/cjs/loader.js:707:30) at Module.m._compile (/Users/i867028/git/github/spartacus/node_modules/ts-node/src/index.ts:400:23) at Module._extensions..js (internal/modules/cjs/loader.js:718:10) at Object.require.extensions.(anonymous function) [as .ts] (/Users/i867028/git/github/spartacus/node_modules/ts-node/src/index.ts:403:12) at Module.load (internal/modules/cjs/loader.js:605:32)

hackergil commented 5 years ago

In general the approach and the idea is very good. I have the following concerns:

The team (everyone who checks code in) has to be well aware of what the commit format is
We don't want to (and we won't) rewrite git history to fix or amend commits that are not in the rigth format. What's the workaround?
Let's sync up with @Xymmer and @tobi-or-not-tobi to see what they think

marlass commented 5 years ago

We can also check commit messages while doing code review and that should help everyone to learn this format faster.

I agree that we shouldn't change history. We will only be manually adjusting changelog for commits with wrong message format. There shouldn't be a lot of commits to check if we will squash each PR.

marlass commented 5 years ago

I just removed node_modules and run yarn. All dependencies were installed. It is strange that you have the error with conventional-commits-parser missing.

Xymmer commented 5 years ago

we thought this was going back and forth between marcin and gil, but it's back in to do
gil wanted some feedback from bill and tobias

hackergil commented 5 years ago

Changes look good for a first draft. We need a couple of follow up tickets:

One to integrate this to our release process (run as part of the release, publish to github releases)
One to publish the documentation as part of our docs/wiki so that external contributors know

Also, we need to inform all the teams about the new commit format.

marlass commented 5 years ago

Created tasks #413 and #414 After we finish #413 we will send a link with docs to everyone.

marlass commented 5 years ago

First changelog generated without problems, so I think this can be considered done.

SAP / spartacus

Script to generate release Changelog #16

Version control convention

Merge guidelines

Commit Message Guidelines

Commit Message Format

Revert

Type

Scope

Subject

Body

Footer

Generating changelog

Running script

Release check