Commit convention and Merge strategy for Co-op Translator

[skytin1004]

As we prepare to expand the Co-op Translator project and encourage more contributions, it is essential to establish a clear and consistent approach to commit messages and merge strategies. These guidelines are adapted from the conventions used in major open-source projects like Microsoft Semantic Kernel, Microsoft Prompt flow, Apache Iceberg, and Apache Airflow. By aligning with established best practices, we ensure our project remains scalable, easy to navigate, and welcoming to new contributors.

Commit message convention

We propose using the following commit message format to ensure clarity, traceability, and consistency across all commits.

Format

<type>: <description> (#<PR number>)

• type: Specifies the category of the commit (see below for approved categories).
• description: A concise summary of the changes made.
• PR number: The pull request number associated with the commit for traceability.

Approved commit categories

To maintain a consistent and organized history, we propose using the following four categories:

1. Docs:

   • For commits related to documentation updates.
   • Example: Docs: Update installation instructions for clarity (#50)

2. Build:

   • For commits affecting the build system, CI/CD pipelines, or dependencies.
   • Example: Build: Upgrade Python version in Dockerfile to 3.10 (#55)

3. Translator:

   • For commits that affect the core translation logic or related features.
   • Example: Translator: Improve handling of image-based text translation (#60)

Merge strategy: Squash and Merge

We recommend using Squash and Merge as the default merge strategy for the following reasons:

• Clean history: Squashing combines multiple commits from a PR into a single commit, keeping the history linear and easy to follow.
• Consistency in commit messages: Allows us to rewrite the final commit message to align with our commit message convention, even if the original commits were not formatted consistently.
• Reduced noise: Prevents small, intermediary commits (e.g., “fix typo” or “adjust formatting”) from cluttering the project history.

Example of squash and merge

Multiple small commits like:

fix typo
update README
improve formatting

Should be squashed into a single meaningful commit message:

Docs: Improve documentation formatting and content clarity (#65)

[skytin1004]

Hi @leestott, @timothycdc,

To ensure the scalability and maintainability of the Co-op Translator project, I propose that we standardize on commit messages and adopt squash merge as our primary merge strategy.

I've reviewed practices used by major open-source projects such as Microsoft and Apache (Microsoft Semantic Kernel, Microsoft Prompt flow, Apache Iceberg, and Apache Airflow).

I think this approach will help manage contributions more effectively as the project grows.

If this works for both of you, I'll proceed with updating the CONTRIBUTING.md file with detailed guidelines. Please let me know if you have any feedback or suggestions when you get a chance.

Thank you for your time and support!