Sebastien Allgeyer

I am a scientific software developer, applying numerical methods to real world issues

4 minute read

Guidelines on generating git commit message

Introduction

Peer review is a process of evaluating and improving the quality of code by having other developers examine and comment on it. Peer review can help to detect bugs, improve readability, maintain consistency, and enforce best practices. Git commit messages are short descriptions of the changes made to the code, which can help to track the history and purpose of the project. Git commit messages should follow a standard format and style to make them clear and informative. This document provides some general guidelines for the peer review process and the git commit message standardization.

Peer Review Process

The peer review process can vary depending on the project, the team, and the tools used, but here are some common steps and tips:

  • Provide a clear and concise description of the code changes, the motivation, and the expected outcomes. You can use the git commit message or the pull request description to do this.

  • Before submitting the code for review, make sure it is well-tested, formatted, documented, and follows the coding standards of the project.

  • Create a pull request when you have finished the development and are ready to submit the code for review. A pull request is a request to merge your code changes to the main branch of the project.

  • Choose an appropriate reviewer or reviewers who have the relevant expertise and experience to review your code. You can use tools like GitHub or GitLab to assign reviewers and request reviews.

  • Be open and respectful to the feedback and suggestions from the reviewers. Respond to their comments and questions, and make the necessary changes to the code if needed.

  • Reviewers should also be respectful and constructive in their feedback. They should focus on the code quality, functionality, readability, and performance, and not on personal preferences or opinions.

  • Reviewers should provide specific and actionable comments, and explain the reasons behind their suggestions. They should also acknowledge the positive aspects of the code and appreciate the efforts of the developer.

  • Reviewers should review the code in a timely manner and avoid unnecessary delays. They should also communicate with the developer if they need more time or information to complete the review.

  • Reviewers should respect the ownership and the authorship of the code. They should not try to rewrite the code the way they would write it, unless there is a clear and objective reason to do so. They should also avoid making changes to the code without the consent of the developer.

  • Once the review is completed and the code is approved, the developer can request a specific person to merge the code to the main branch. The person who merges the code should be someone who has the authority and the responsibility to do so, such as the project manager, the team leader, or the senior developer.

Here is a checklist for the reviewers to follow when reviewing the code:

  • The person who merges the code should also make sure that the code passes the pipeline, which is a series of automated tests and checks that ensure the code quality and functionality. The pipeline can include tools like continuous integration, continuous delivery, code analysis, code coverage, etc. If the code fails the pipeline, the person who merges the code should notify the developer and ask them to fix the issues before merging the code.

  • Comment on the code, not on the developer. Use constructive and polite language, and avoid personal attacks or criticism.

  • Check for consistency in the code style, naming, indentation, spacing, and formatting. Use tools like linters or code formatters to automate this process.

  • Check for coding standards and best practices, such as modularity, readability, documentation, error handling, testing, etc. Refer to the project guidelines or the common conventions for the programming language or the framework used.

  • Check for functionality and performance, such as correctness, efficiency, security, scalability, etc. Use tools like unit tests, code coverage, code analysis, benchmarks, etc. to verify the code behavior and quality.

  • Check for readability and maintainability, such as clarity, simplicity, comments, documentation, etc. Use tools like code review or code quality metrics to assess the code complexity and readability.

Git Commit Message Standardization

Git commit messages are important for documenting the changes made to the code and communicating with other developers. A good git commit message should follow these general rules:

  • Use the present tense, which means describing what the code does, not what it did, such as “Update documentation” or “Refactor code”.

  • Use the imperative mood, which means using commands or instructions, such as “Fix bug” or “Add feature”.

  • Use a capital letter for the first word, such as “Improve performance” or “Remove unused code”.

  • Use a period (.) at the end of the message, such as “Fix typo.”

  • Use a maximum of 50 characters for the first line of the message, which is the summary or the subject of the commit. If the message is longer, use a blank line and then a more detailed description in the following lines, with a maximum of 72 characters per line.

  • Use bullet points or dashes to list multiple changes in the same commit, such as “- Fix bug in login function” or “* Add validation to input fields”.

  • Use categories to indicate the type or the scope of the change, such as “feature”, “update”, “remove”, “add”, “test”, “fix”, “chore”, “refactor”, etc. Use a colon (:) after the category, such as “feature: Add login function” or “fix: Correct spelling error”.

  • Use brackets ([ ]) to include the issue id related to the change, if applicable. Use a hash (#) before the issue id, such as “fix: Resolve memory leak [#123]” or “update: Improve documentation [#456]”.

You May Also Enjoy