Appearance

Writing Commit Messages ​

Commit messages are an essential part of version control in GitHub. They document the changes you make, explain the reasons behind those changes, and help others (including your future self) understand the history and evolution of a project. Clear and descriptive commit messages are especially important in collaborative environments, where multiple contributors rely on them to stay aligned.

Why good commit messages matter:

  • They make it easier to understand what changed without reading the code.
  • They help trace bugs or regressions by reviewing past commits.
  • They improve teamwork by keeping everyone aligned on updates and progress.

General Guidelines ​

  1. Be clear and specific. Summarize what changes and why.
  2. Use the present tense and imperative mood. Write as if giving a command, e.g., “Add mesh refinement script” instead of “Added mesh refinement script.”
  3. Keep the first line short (under 50 characters). If more detail is needed, add a blank line and then a longer description.
  4. Group related changes into a single commit. Don’t mix unrelated updates.
  5. Reference related issues or features if applicable (e.g., “Fix issue #12”).

Example Commit Messages ​

Good Examples ​

Add function to export mesh with region markers
Update README with installation instructions
Fix boundary condition bug in electromagnetic solver
Refactor preprocessing script for clarity and reusability

Poor Examples ​

update
final changes
fixed stuff

These provide no context and make it difficult to understand what was actually changed.

python
<type>: <short summary>

<optional detailed description>

<optional reference>

Example:

python
feat: Add support for custom boundary markers

Allow users to specify named boundary regions directly from Salome export.
Improve clarity when defining boundary conditions in FEniCS.

Common types:

  • feat: – add a new feature
  • fix: – fix a bug
  • docs: – update documentation
  • refactor: – restructure code without functional changes
  • test: – add or modify tests

Summary ​

A good commit message should read like a directive — describing what the commit does right now. Writing messages in present tense (“Fix bug” instead of “Fixed bug”) keeps them consistent and action-oriented, aligning with professional Git practices.

Consistent, descriptive commits are a small effort that make a big difference in collaborative research and development.