background

A good project is usually the result of multiple people working together. When you iterate on a version and want to review it to see which features were added and which features were improved, do you still rely on the GitLab/Github history to do that? 2021, say NO to this tedious and NO statistical classification of the second disc!

When the current version is released, do you want people to be able to keep track of the project iteration and receive the project iteration push? Are you still manually assembling the statements and sending them to the IM you want to notify one by one? If a large number of IMS need to be notified, they may not be notified or the description may be inaccurate. At the same time, the description of the template is not consistent, the description may not be specific to which project, which branch, which version. In the age of information automation, how do we achieve targeted precision delivery?

The solution

A friendly update log (Changelog.md) allows users and developers to better know what changes are made in each release, whether they are new feature points or improvements to the original features of the project. At the same time, the update log provides an intuitive basis for project recovery, facilitating quick browsing. With a regular update log, you can still remember what you did on an iteration a month later.

The standard update log has unified constraints on everyone’s Git commit message, and the unified git commit message submission method makes the project iteration content more unified and clear at a glance.

The submission constraint specification is as follows:

<type>[optional scope]: <subject> 
Copy the code

Type The type is as follows:

-Blair: Feat. New feature fixes bugs, docs style, refactor, test. Add chore for testing: other modifications, such as build process, dependency managementCopy the code

Example:

Feat: Pay two qing merchant settlement processCopy the code

Once your project is published, in order for everyone to be aware of the iteration of your project, you need a uniform and standardized release template, plus a robot that automatically notifies you of the IM you want to publish in real time. Based on the current IM used by the team is Feishu, which is connected with feishu robot. When the project is released, the robot will be triggered to make directional announcement and realize instant notification.

From the above two starting points, @du/ Changelog-Robot is produced. @du/ Changelog-robot Based on the mature Conventional – Changelog, the corresponding Changelog.md is generated according to local tags. And the original update log output to the flying book robot, real-time notification to the corresponding group.

Overall solution architecture diagram

[1.1]

In the process of user NPM publish, there are two hooks in the publish process, prepublishOnly and PostPublish.

With hooks in place, we can roughly allocate the entire functionality based on when the hooks are triggered. Changelog. md is generated before a project is released. After the project is released, a notification is sent to the corresponding group in real time.

As shown in Figure [1.1], the overall scheme is divided into two modules, which generate the Changelog. md module and the feishu robot notification module. The two modules exist independently and command use does not affect each other.

• Generate the Changelog. md module: This module mainly solves the content disorder of Changelog. md caused by collaborative development of many people on the basis of Xconventional changelog open source package, and adds the function of automatic submission of Changelog. md according to the principle of NPM version XXX.

• Real-time notification module: this module is mainly combined with the API of flying book robot, and the generated changelog. md content is informed to the corresponding flying book group.

Plan implementation

In order to automatically generate the required Changelog. md documents before the release of the project, and automatically notify in the flying book group in real time after the successful release of the project, a set of solutions was designed after the research of Conventional CHANGELOG and flying book robot. The scheme is divided into two modules, which generate changelog. md module and feishu robot notification module.

How do I generate Changelog.md

Conventional – Changelog is a mature toolkit for generating changelog.md based on templates.

Convention-changelog generates file streams, mainly relying on Git log, and obtains all commit information under the corresponding tag. The principle is as follows:

1, get all the tags under the current repository

var reverseTags = context.gitSemverTags.slice(0).reverse()
Copy the code

2. Form a readable stream

var streams = reverseTags.map((to, i) => {
  const from = i > 0
  ? reverseTags[i - 1]
  : ''
  return commitsRange(from, to)
})
Copy the code

3, commitsRange method is the key to form a readable stream, the method through the git log, according to your set of templates to generate the corresponding information, in which the args array,

• the args [0] : “log”

• the args [1] : “–format=%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci%n-authorName-%n%an%n- rules remail -%n%ae%n

• ARgs [2]: “v1.2.5” // Corresponding tag number

• the args [3] : “- no – merges”

var child = execFile('git', args, {
    cwd: execOpts.cwd,
    maxBuffer: Infinity
  })
Copy the code

After the above code, it is actually executed on the console:

Git log --format=%B%n-hash-%n%H% n-gittags -% N %d%n-committerDate-%n%ci% n-authorname -%n%an% n-rules -%n% AE %n change your own version number --no-mergesCopy the code

All commits under the current tag are returned:

1.2.30 - hash - 3 c5949d1db635dcfe6fa4dc0331b9003ca8f091c - gitTags - (tag: V1.2.30) -committerDate- 2020-10-25 14:33:03 +0800 -authorName- rules - [email protected] fix: Test old changelog functions - NPM tag, 1.2.30, Based on 1.2.29 played tag - hash - d60c34320bff8fc807e4decd139755bd4b4c07a4 - gitTags committerDate -- the 2020-10-25 14:32:56 + 0800 -authorName- chengli -authorEmail- [email protected] ....Copy the code

These messages form corresponding readable streams, as shown in Figure 2.1.1-1:

Conventional-Changelog work flow

The following is for convenience

Replace Conventional -changelog with CC

Cc automatically generates version information based on Git logs and Git commitMsg

Git commitMsGs must comply with the commit specification and git logs must be valid

Cc comes with a number of preset configuration items, which can be found at github.com/conventiona… changelog/tree/master/packages/conventional-changelog-core

1. Git logs –pretty — is the source of all local Git records.

2. With the Library Thorugh2, create a transform stream and pipe the readable stream into the transform stream. Every time you push commitMsg data into a readable stream, the _transform of the conversion stream is automatically triggered. If we pass in a custom transform function during initialization, the transform is executed.

3. Instead of passing in the default transform function, the commit is grouped by git tag.

4. Internal verification version number based on semver.valid. Therefore, the version number must match xxx.xxx.xxx. Commit that does not match the format will be ignored.

5. The CC template rendering engine uses handlebar and renders in MD file format.

6. The assembled version commit information is pushed again to a new transformation stream and processed into MD format data using handleBar.

7. Cc finally returns a conversion stream, which generates a steady stream of Changlog data by simply configuring the write stream.

8. Nodejs. Cn/API/stream….

Const changelogStream = conventionalChangelog({preset: 'Angular ', // Preset changelog type WARN: function (warning) { console.log('warning; ', warning)}, appEnd: false, // a+ releaseCount: 0, // 0 function (commit, cb) { if (typeof commit.gitTags === 'string') { var match = rtag.exec(commit.gitTags) rtag.lastIndex = 0 if (match) { Commit. Version = match[1] // Version must comply with xx.xx.xx format}} if (commit.committerDate) {commit.committerDate = moment(new) Date(commit.committerDate)). Format ('YYYY-MM-DD HH: MM :ss') Return cb(null, commit)}}) Changelogstream.pipe ('./ Changelog.md ')Copy the code

】 【 2.1.1-1 *

The readable stream is parsed in several columns and finally assembled into the data format shown in Figure 2.1.1-2:

Const changelogStream = conventionalChangelog({preset: 'Angular ', // Preset changelog type WARN: function (warning) { console.log('warning; ', warning)}, appEnd: false, // a+ releaseCount: 0, // 0 function (commit, cb) { if (typeof commit.gitTags === 'string') { var match = rtag.exec(commit.gitTags) rtag.lastIndex = 0 if (match) { Commit. Version = match[1] // Version must comply with xx.xx.xx format}} if (commit.committerDate) {commit.committerDate = moment(new) Date(commit.committerDate)). Format ('YYYY-MM-DD HH: MM :ss') Return cb(null, commit)}}) Changelogstream.pipe ('./ Changelog.md ')Copy the code

2.1.1-2 * 】

Take the data and generate the flow required to meet the MarkDown specification based on the HBS template

*{{#if scope}} **{{scope}}:** {{~/if}} {{#if subject}} {{~subject}} {{~else}} {{~header}} {{~/if}} {{~! -- commit link --}} {{#if @root.linkReferences~}} ([{{shortHash}}]( {{~#if @root.repository}} {{~#if @root.host}} {{[email protected]}}/ {{~/if}} {{~#if @root.owner}} {{[email protected]}}/ {{~/if}} {{[email protected]}} {{~else}} {{[email protected]}} {{~/if}}/ {{[email protected]}}/{{hash}})) by: {{authorName}} {{committerDate}} {{~else}} {{~shortHash}} {{~/if}} {{~! -- commit references --}} {{~#if references~}} , closes {{~#each references}} {{#if @root.linkReferences~}} [ {{~#if this.owner}} {{~this.owner}}/ {{~/if}} {{~this.repository}}#{{this.issue}}]( {{~#if @root.repository}} {{~#if @root.host}} {{[email protected]}}/ {{~/if}} {{~#if this.repository}} {{~#if this.owner}} {{~this.owner}}/ {{~/if}} {{~this.repository}} {{~else}} {{~#if @root.owner}} {{[email protected]}}/ {{~/if}} {{[email protected]}} {{~/if}} {{~else}} {{[email protected]}} {{~/if}}/ {{[email protected]}}/{{this.issue}}) {{~else}} {{~#if this.owner}} {{~this.owner}}/ {{~/if}} {{~this.repository}}#{{this.issue}} {{~/if}}{{/each}} {{~/if}}Copy the code

Analyzed the main core code generated by Xconvention-Changelog for Changelog. md, but the current open source xconvention-Changelog library cannot meet the demand, and it does not submit the generated Changelog. md file. Not properly synchronizing version tags for projects with multiple people working on the same branch, and not verifying user manual changes to version for projects that require NPM publish, can result in the generated Changelog.md content being disordered and not delivering the desired effect.

After doing research on relevant toolkits, summarize the extent to which the current toolkits meet the needs according to the functions they need to implement, improve the functions based on the existing toolkits, and optimize iteratively according to user needs. Toolkit iteration process:

If you manually change version, publish successfully, but the corresponding commit message mount version number is not correct:

• After the information is submitted for the first time, the version of package.json is manually updated. Because the normal publishing process is not followed, no tag is generated during the current publishing. The generated Changelog. md is shown as follows [2.1.1-3] :

2.1.1-3 * 】

• Based on Figure [2.1.1-3], after submitting information for the second time, the version of package.json is manually updated, and the generated Changelog. md is shown in Figure [2.1.1-4]. So the submission information for both versions is merged and hangs on the current version. If the user manually updates the version each time, all subsequent commit messages will be scrunched together and mounted on the current version until a tag is inserted to delimit the commit information.

】 【 2.1.1-4 *

• The user uses NPM version XXX to tag the untagged version. The untagged version is tagged to the current version. Figure [2.1.1-5] :

2.1.1-5 * 】

• Submit the correct version based on the last version tagged, that is, NPM version XXX. At this time, the content will be classified and displayed based on tag, which is the effect we want to achieve, as shown in Figure [2.1.1-6] :

【 2.1.1-6] *

Solution: Through the above analysis, it is concluded that the commit message must be tagged by NPM version XXX to be properly categorized and displayed.

2. Changelog. md is generated correctly. After the user executes NPM publish, the Changelog. md file exists in the local temporary storage area, and the user needs to submit it again, as shown in Figure [2.1.1-7].

2.1.1-7 * 】

Solution: Similar to the principle of NPM version XXX, integrated into the toolkit, automatically help users to submit information

3. Collaborative development of multiple users in the same branch, local tags are not synchronized, resulting in confusion in the classification of the same commit message content in Changelog. md, as shown in Figure [2.1.1-8] :

2.1.1-8 * 】

Solution: Before changelog.md is generated, pull remote tags and push local tags after changelog.md is generated

Overall Architecture

It mainly relies on the function of The Xconventional Changelog open source package to verify the project version number and tags in the early generation stage, and synchronize local and remote. Guide users to generate compliant versions prior to release and automatically help users submit records.

• The overall scheme design is shown in Figure [2.1.2-1] :

2.1.2-1 * 】

Work flow chart

The scheme is a guide, just like the skeleton of the human body, supporting the whole structure. With the overall design scheme, the next step is to design the code flow, realize the desired function, and implement the idea.

• The working process is as follows [2.1.3-1]

】 【 2.1.3-1 *

Full rendering

After the whole process, interactive commands will appear on the console for users to generate version numbers and tag, as shown in Figure [2.1.4-1] :

[2.1.4-1] *

According to NPM version specification, select the required version number and successfully generate Changellog. md, as shown in Figure 2.1.4-2. The generated file will be automatically saved and submitted for users (the function here refers to the logic of NPM Version XXX, and the contents of temporary storage area are processed by black box). Figure [2.1.4-3]

[2.1.4-2] *

[2.1.4-3] *

Real-time notification module

How to automatically arouse the flying book robot to notify the group when NPM publish requires us to combine the flying book developer API and form a class to complete a series of operations.

How to dock with the flying book robot

Users can create their own robots, according to the feishu developer’s documentation.

With robots, we need to notify groups in the style of Changelog.md.

It is necessary to consult the notification message API of Feizhu robot and select the API that meets the requirements to display the notification. According to the input format of API, it is necessary to combine the flows generated by Conventional – Changelog and assemble them into the format that meets the requirements. Flybook message cards support part of markdown format.

Get the Robot APP_ID, APP_SECRET, APP_VERIFICATION_TOKEN, write a Robot class, realize the docking function. At the same time, users can make specific configurations for the notified group.

Overall Architecture

The overall scheme architecture is shown in Figure 2.2.2.

[2.2.2-1] *

Work flow chart

Make the following code flow design with the scheme design drawing, as shown in FIG. [2.3-1]

】 【 2.2.3-1 *

Full rendering

The effect of the PostPublish hook triggering the notification is shown below

】 【 2.2.3-1 *

application

At present, the front-end group tool library is basically connected to @du/ Changelog-Robot, realizing real-time notification of projects and generating specifications changelog.md.

Reference documentation

• From Commit normalization to publishing custom CHANGELOG templates: juejin.cn/post/684490…

• AngularJS Git Commit Message Conventions: docs.google.com/document/d/…

But – changelog: github.com/conventiona…

• inquirer: www.npmjs.com/package/inq…

• Promise-q: www.npmjs.com/package/q

• read – PKG – up: www.npmjs.com/package/rea…

• node api： nodejs.cn/api/

Article | front-end platform

Pay attention to the object technology, hand in hand to the cloud of technology

Join us and send your resume to [email protected]