Git Commit Message Standards for ML Projects¶

ChatGPT Prompt for Git Commit Message

To create a standardized git commit message using ChatGPT, provide the following details: the output of git diff (1) command (including one or more modified files), the JIRA story number, and optionally, any additional context. ChatGPT will generate the appropriate commit message based on these inputs.

To ensure you get enough information from git diff to create a rich git commit message with ChatGPT, use the following command: git diff -U10 my-script.py.

Example Prompt¶

Copy and paste the example prompt in ChatGPT or similar chat:

Generate git commands for staging and committing the following changes. Follow
the structure:

<type>(<scope>): <subject> [#issue_number | #jira_key]

Include all modified files in the `git diff` command. Provide the
complete `git add` and `git commit` commands, including the body and 
footer. Select the right git commit types with emojis. Limit 
comments to 72 characters per line and code lines to 79 characters. 

Output of `git diff` command:

[Please insert the output of the git diff here]

JIRA story number:

[Please enter the JIRA story number here]

Additional Context (Optional):
-----------------------------

[Please insert additional context]

Commit types:
-------------
Here’s the list of git commit types with emojis included:

### Commit Types:

- ✨ feature
- 🐛 bugfix
- 📊 data
- 🧪 experiment
- 🤖 model
- 📝 docs
- ♻️ refactor
- ✅ test
- 🔧 chore
- 🚑️ hotfix
- ⚡️ performance
- 🔒 security
- 🚀 build
- 👷 ci
- 🔬 hyperparameter-tuning
- 🧹 preprocessing
- 🖼️ visualization
- 📈 evaluation
- 📦️ deployment

Example of Expected Output:
---------------------------

git add mkdocs.yml poetry.lock pyproject.toml
git commit -m "✨(deps): add mkdocs versioning and testing dependencies [#JIRA-123]

Added dependencies for MkDocs versioning and testing to enhance
documentation and development workflows. Updated pyproject.toml
with the following:
- mkdocs-glightbox: to support image lightboxes in documentation
- mike: to manage multiple versions of documentation

Updated poetry.lock with new packages:
- importlib-resources: for resource management in tests
- mike: for documentation version management
- mkdocs-glightbox: for enhanced documentation visuals
- verspec: for flexible version handling

These changes improve documentation flexibility and testing coverage.

Footer notes:
- Consult package documentation for more details.
"

Running the Git Command¶

To commit your changes with the generated message, run the following command in your terminal:

git add utils/helpers.py
git commit -m "♻️ refactor(helpers): update pi precision and greeting format [#JIRA-123]

Updated the `calculate_area` function to use a more precise value
of pi (3.14159) for improved accuracy in area calculations. Also,
refined the `greeting` function to include a comma for better
readability in the output.

These changes enhance both the mathematical accuracy of area
calculations and the user experience with improved greeting
formatting.

Footer notes:
- Consider further enhancements to include localization
  for the greeting function.
"

Include this admonition in your docs/how-to-guides/git-commit-message-standards.md file. This example explains how to request a standardized git commit message from ChatGPT, providing a detailed prompt and the expected output.

Introduction

Clear, informative commit messages are vital for effective team collaboration in machine learning projects. This guide provides standards and tools for creating standardized commit messages, including how to reference GitHub issue numbers or Jira keys. We follow the Conventional Commits specification.

Commit Message Structure

Commit messages should follow this structure:

<type>(<scope>): <subject> [#issue_number | #jira_key]

<body>

<footer>

Components¶

Type: Category of your commit.
Scope: Area of the codebase affected.
Subject: Brief description of changes, including issue tracker reference.
Body: Detailed explanation of changes and reasoning.
Footer: Additional notes or references.

Commit Types

Maintain consistency and organization with these commit types:

Type	Description
`feature`	New features or enhancements
`bugfix`	Bug fixes
`data`	Data processing or management changes
`experiment`	Experimental or exploratory code changes
`model`	Model development, testing, or deployment changes
`docs`	Documentation additions or updates
`refactor`	Performance enhancements without functionality changes
`test`	Test writing or fixing
`chore`	Routine tasks or non-production code updates
`hotfix`	Critical bug fixes
`performance`	Performance improvements
`security`	Security-related changes
`build`	Changes that affect the build system or external dependencies
`ci`	Changes to CI configuration files and scripts
`hyperparameter-tuning`	Changes related to hyperparameter tuning
`preprocessing`	Data preprocessing changes
`visualization`	Visualization-related changes
`evaluation`	Evaluation-related changes
`deployment`	Deployment-related changes

Best Practices

Concise Subject: Keep it short and descriptive.
Imperative Mood: Phrase as an instruction, e.g., “fix” not “fixed”.
Capitalized Subject Line: Start with a capital letter.
No Period in Subject Line: Treat it as a title.
Separate Body with a Blank Line: For tool compatibility.
Explain What and Why: Not just how, in the body.
Reference Issues and Pull Requests: Include relevant links for context.

Examples¶

Here are some examples of commit messages that meet our standards:

feat(auth): add user authentication feature [#DATA123]

Added a new user authentication feature to enhance security.
This includes login, registration, and password recovery.

Footer: Reviewed by Jane Doe

fix(data): resolve data loading error [#GH45]

Fixed an issue where data loading was failing due to incorrect file paths.
Updated the file paths and added error handling.

Footer: Closes #GH45

docs: update API documentation

Improved the API documentation to include new endpoints and usage examples.
Fixed typos and clarified descriptions.

Footer: Documentation reviewed by the tech writing team

VS Code Extensions

Enhance commit message standardization with these VS Code extensions: - Gitmoji for VS Code: Add emoji to commit messages. Gitmoji. - Commit Message Editor: Enforce structured commit messages.

Reference for Best Practices

For an in-depth understanding, refer to Git Commit Message Best Practices.

Conclusion

By following these guidelines, our team can ensure a uniform and informative history in our repository, turning commit messages into a rich log that enhances clarity and streamlines collaboration.