HdacHdac

Menu Open

search result

Frequently Searched Words
Menu Close

NEWS

Latest News

Stay updated with the latest news and event on RIZON

Developers’ Journal

Effective management of Commit History: Conventional Commits

Feb 15th, 2020

For today’s article, I’m going to share how we progress our development. Especially since when we first started the project, we had discussions about how to leave a Commit Message. It seems like overall, many projects don’t pay much attention to the Commit Message Format while others have defined their own rules.

We have decided to introduce Conventional Commits to the project and share some of the thoughts and feelings we have heard in the process.

What is a good Commit Message?

First, we write a chunk of code in semantic units, then, take a snapshot of the chunk and save the snapshot to VCS (Version Control System). Every time one commits, one must leave an explanation comment about the commit. The Commit Message that is written is a clue to understanding the meaning of the code. It also gives insights related to the flow and direction of the project development. Given this, it makes sense that the Message should be concise and clearly explain the meaning of the code in order to facilitate the comprehension of the Commit content.

So how to write a good Commit Message? Linus Tovalds describes a good Commit Message as follow:

Header line: explain the commit in one line (use the imperative)Body of commit message is a few lines of text, explaining things    in more detail, possibly giving some background about the issue    being fixed, etc etc.The body of the commit message can be several paragraphs, and
please do proper word-wrap and keep columns shorter than about
74 characters or so. That way "git log" will show things
nicely even when it's indented.
Make sure you explain your solution and why you're doing what you're doing, as opposed to describing what you're doing. Reviewers and
your future self can read the patch, but might not understand why a particular solution was implemented.
Reported-by: whoever-reported-it
Signed-off-by: Your Name <youremail@yourhost.com>

The Commit Message is divided into Header, Body, and Footer. In the Header, a single line summarizing the Commit is written in the form of an imperative. The body does not describe how it is implemented, but rather provides background related to the issue, the proposed solution, and explanations why you wrote this implementation. Finally, the Footer helps keep track of the Reporter and Signer.

By specifying the message format, developers should not worry about how to write a Commit Message. Instead, they encourage developers to write what the Commit Message should contain.

The way Linus’ Commit Message was written affected numerous Commit Message Formats. And, our team decided to opt for a Conventional Commits which is one of them.

What is Conventional Commits ?

/svg+xml;utf8,<svg preserveAspectRatio=\"none\" viewBox=\"0 0 1 1\" xmlns=\"http://www.w3.org/2000/svg\"><line x1=\"0\" y1=\"0\" x2=\"1\" y2=\"1\" stroke=\"rgba(41, 41, 1)\" /></svg>"); background-size: 1px 1px; background-position: 0px calc(1em + 1px);">Conventional Commits is a Commit Message Specification, inspired by the /svg+xml;utf8,<svg preserveAspectRatio=\"none\" viewBox=\"0 0 1 1\" xmlns=\"http://www.w3.org/2000/svg\"><line x1=\"0\" y1=\"0\" x2=\"1\" y2=\"1\" stroke=\"rgba(41, 41, 1)\" /></svg>"); background-size: 1px 1px; background-position: 0px calc(1em + 1px);">Angular Commit Guidelines. The purpose of this specification is, first, to allow developers to write Commit Messages dovetailing with /svg+xml;utf8,<svg preserveAspectRatio=\"none\" viewBox=\"0 0 1 1\" xmlns=\"http://www.w3.org/2000/svg\"><line x1=\"0\" y1=\"0\" x2=\"1\" y2=\"1\" stroke=\"rgba(41, 41, 1)\" /></svg>"); background-size: 1px 1px; background-position: 0px calc(1em + 1px);">SemVer, then, to automatically determine the Semantic Version of a project, and finally, to automatically generate a CHANGELOG upon production release. Conventional Commit Message is written as below:

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

How to write a Message

  • fix: is used when we have backward-compatible bug fixes. The Message type relates to the Semantic Version ’s PATCH.
  • feat: This type is used when we add new functionalities in a backward-compatible manner. The Message type relates to the Semantic Version’s MINOR.
  • BREAKING CHANGE: Starting an optional Body or optional footer with the text BREAKING CHANGE: means that it will not be compatible with existing APIs. It relates to the Semantic Version ‘s MAJOR and can be applied to any Message Type. As an option, you can include ! in the Headline to notify that the Body or Footer contains a BREAKING CHANGE.
  • You can add other types than fix and feat. Commonly used [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test]. Note that you are not required to use these types. Projects can define their own set of types and set of scopes.
fix(release): need to depend on latest rxjs and zone.jsThe version in our package.json gets copied to the one we publish, and users need the latest of these.

Example 3 for fix type, means change corresponds to Semantic Version’s PATCH.

chore!: drop Node 6 from testing matrixBREAKING CHANGE: dropping Node 6 which hits end of life in April

Example 4 shows the change corresponding to the Semantic Version’s MAJOR since the body starts with BREAKING CHANGE, A! is inserted between the type and colon on the headline to indicate that the BREAKING CHANGE is in the body.

feat(docs-infra): add v8 to the version picker in the navbar(#35196)The v8.angular.io should be ready shortly.PR Close #35196

Close # 123 and similar Meta-information are written in the footer as in Example 5.

Advantages of Conventional Commits

Commit History of Repository using Conventional Commits
  • Types and Scopes make it easy to identify which kind of changes are being reflected in which scope by simply scanning the Commit History Tree.
  • If one writes according to the message format, developers will be able to consciously Commit and improve the overall code quality.
    * Since the message requires writing a specific Headline, it is effective to fit the meaning of the Code in one clear Commit.
    * Fixes or features must use separate Commit with different characteristics
  • Reduce the burden of managing Versioning and CHANGELOG.
    * CHANGELOG can be generated by using scripts parsing Commit Message according to type.
    * Every time developers commit, they directly record the type corresponding to the Semantic Version, minimizing versioning mistakes and eliminating the need to manually manage whether a breaking change exists or a feature has been added.

Valuable Tools to Use with Conventional Commits

We will post additional topics in the future covering rich and diver challenges. Stay tuned :)

References

 

PRIVACY POLICY

1. Introduction.

Hdac Technology AG respects the privacy of its Members, Contributors, Users or Clients and is dedicated to controlling the use and disclosure of information provided by Members, Contributors, Users or Clients using the Site. This Privacy Policy (the “Privacy Policy”) sets forth Hdac Technology AG’s policies regarding collection, storage, access, use and disclosure of information relating to a Member’s, Contributor’s, User’s or Client’s registration and use of the Site. Any terms not defined herein shall have the meaning set forth in the Terms & Conditions, the Transaction Terms & Conditions or the User Agreement.

2. Information Collection, Use And Disclosure Activities.

2.1 Registration Information.

To ensure that only legitimate entities and individuals are able to access the non-public areas of the Site and enter into transactions, we require each potential Member, Contributor, User or Client to, by using the Registration Page on the Site, provide (i) information regarding themselves (including name, e-mail address, job title, work address and work phone number), and (ii) information regarding their Company (including Company name and parent Company’s name and address). Upon receipt of Your registration data, Hdac Technology AG may contact You or Your Company to obtain other background information used by Hdac Technology AG to evaluate an applicant's qualifications for Membership, Contribution and/or Participation. Other than as specified in this Privacy Policy, the registration information will be used only internally by Hdac Technology AG and will not be disclosed to third parties without the applicable Member’s, User’s or Client's prior written consent. Notwithstanding of the before mentioned, Hdac Technology AG is obliged to report suspicious transactions and facts about individuals including Contributors to the relevant authorities without further notification and without becoming liable for any damage such action may cause.

2.2 References.

In addition to the information specified in Section 2.1, Hdac Technology AG may require Members, Contributores, Users or Clients or prospective Members, Contributors, Users or Clients to provide Hdac Technology AG with Company references to allow Hdac Technology AG to verify a Company’s capacity, legitimacy and reputability. Hdac Technology AG may provide such references to parties with which a Member, User or Client enters into a Negotiation to assure such parties that Company can meet its prospective obligations thereunder.

2.3 Member, Contributors, User or Client Profile.

Each Member, User or Client will create a Member, Contributor, User or Client profile that includes, among other things, information about this Member, Contributor, User or Client. Information in a Member, Contributor, User or Client profile are accessible only by the applicable Member, Contributor, User or Client, the Member, User or Client’s Group Administrator and Hdac Technology AG. Certain Member, Contributor, User or Client profile information will be provided to the parties engaged in a Negotiation in accordance with Section 2.5. Other than as permitted under this Privacy Policy, Member, Contributor, User or Client profile information will not be disclosed to third parties without the applicable Member, Contributor, User or Client's prior written consent.

2.4 Member, Contributor, User or Client Information.

(a) Hdac Technology AG may collect, use and disclose both on and off the Site, for marketing and other purposes, certain general, demographic and statistical information regarding Site usage and transactions. (b) To assist Member, User or Clients in selecting companies they may do business with through the Site, Hdac Technology AG may make available to Member, Contributor, User or Clients and non-Member, Contributor, User or Clients certain performance statistics of all Companies, provided that such statistics shall not include any Company-identifiable pricing information.

2.5 Technical and Usage Information.

To operate the Site, enhance its functionality, and ensure that Members, Contributors, Users or Clients Negotiations and communications are convenient, dependable and secure, Hdac Technology AG may collect, store and use technical and Site usage information relating to a Member, Contributor, User or Client's activities on the Site. Such information includes the Internet Protocol (“IP”) address from which a Member, Contributor, User or Client accesses the Site, which is used only internally by Hdac Technology AG as required for server operation and other technical uses, and is not disclosed to Members, Contributors, Users or Clients or other persons. Hdac Technology AG may also track the pages of the Site accessed by Members, Users or Clients.

2.6 Member, Contributor, User or Client Communications.

Hdac Technology AG may use Member, Contributor, User or Client contact information, such as e-mail addresses, to communicate with Members, Users or Clients regarding registration and transactions, to notify Members, Contributors, Users or Clients of changes in Site functionality and features, product and service updates, policy changes, billing and other activities relating to a Members, Contributors, Users or Client's use of the Site, and for marketing purposes.

2.7 Legal Compliance.

In addition to the disclosures permitted pursuant to this Privacy Policy, Hdac Technology AG may provide Member, Contributor, User or Client information in connection with legal, administrative or judicial inquiries, claims or orders to the extent necessary to comply therewith or to enforce a User Agreement.

3. Collection And Use Of Information Using Cookies.

As with many state-of-the-art Internet sites, the Site uses “cookies” to enhance the functionality of the Site and to make transactions and other activities more convenient and efficient for Members, Contributors, Users or Clients. A “cookie” is a file stored locally on computers used to access the Member, Contributor, User or Client account that contains information relating to a Member, Contributor, User or Client's past use of the Site. For example, a cookie may contain information previously entered on a Site form, which may be recalled as default information when that form is accessed at a later time. This prevents re-entry of frequently used information each time a Member, Contributor, User or Client account is accessed. Cookies are also useful in streamlining log-in and in preserving transactional information between sessions. Cookies will likely play an increasingly important role as we enhance the ability of Members, Contributors, Users or Clients to customize the functionality of the Site to better meet their needs and preferences. Most Internet browsers include preference settings that allow users to be notified and control whether cookies are transferred to their computers. Please review Your browser's documentation or “help” feature for more information on that functionality. Although disabling cookies will not affect a Member, User or Client's ability to transact business on the Site, it may make such activities more time consuming.

4. Linked Sites.

The Site may contain hyperlinks through which other Internet websites may be accessed by Members, Contributors, Users or Clients. Hdac Technology AG is not responsible for and cannot make any assurances regarding privacy, or other policies or practices of the operators of such websites. Such links are provided only for the convenience of our Members, Contributors, Users or Clients, and the presence of any link does not imply that Hdac Technology AG endorses, approves or is responsible for such websites.

5. Security.

Hdac Technology AG is very concerned with the security of information relating to our Members, Contributors, Users or Clients' use of the Site and has implemented systems and procedures to prevent unauthorized access to that information including the use of Secure Sockets Layer (SSL) connection and password protection. Each Member, Contributor, User or Client will create its own username and password, the secrecy of which is the sole responsibility of the Member, Contributor, User or Client. In the event the integrity of a Member, Contributor, User or Client’s password is compromised, the Member, Contributor, User or Client shall immediately change its password.

6. Updates To The Privacy Policy.

Hdac Technology AG may update this Privacy Policy from time to time as new features and services become available on the Site and to keep pace with technological developments. The new terms shall be effective ten (10) days after they are initially posted on the Site. It is the responsibility of the Member, Contributor, User or Client to review the latest terms. If You do not agree with updated Privacy Policy, You should immediately cease use of the Site and the Services.