Adopt Conventional Commits Specification in Apache Polaris
- Dominant language
- Java
- Stars
- 2.1k
- Forks
- 522
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 137
Description
### Is your feature request related to a problem? Please describe.
This proposal suggests that **Apache Polaris** adopt the [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) standard for commit messages.
Structured commit messages offer significant benefits, particularly for a modern open-source project like Polaris, which is positioned at the intersection of search, data, and developer productivity.
---
### Motivation
Adopting Conventional Commits provides the following advantages:
* **Improved readability** of commit history, making it easier to understand the intent of changes.
* **Automated changelog generation** with tools like [semantic-release](https://github.com/semantic-release/semantic-release) or [standard-version](https://github.com/conventional-changelog/standard-version).
* **Better release management** via semantic versioning based on commit types (e.g., `fix:` = patch, `feat:` = minor, `BREAKING CHANGE:` = major).
* **Standardized workflow** for both core contributors and external collaborators.
* **Enables CI/CD optimizations** such as impact-based testing, change classification, and conditional deploys.
---
### Inspiration from Other Apache Projects
Several Apache Software Foundation (ASF) projects have adopted structured commit messaging patterns, inspired by or aligned with Conventional Commits:
* [Apache Airflow](https://github.com/apache/airflow):
* Uses prefixes such as `feat`, `fix`, `docs`, `test`, `chore`, and `refactor`.
* Enforces commit format for PR merges. See: [Airflow Commit Message Guidelines](https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst#commit-message-guidelines)
* [Apache Superset](https://github.com/apache/superset):
* Actively encourages Conventional Commits in its [contributing guide](https://github.com/apache/superset/blob/master/CONTRIBUTING.md#commit-messages).
* Uses changelog automation based on commit metadata.
* [Apache Pinot](https://github.com/apache/pinot):
* Also encourages meaningful, structured commit messages.
Adopting this in Apache Polaris aligns with best practices adopted across the foundation and supports long-term project maintainability and automation.
---
### Compatibility
This is a **non-breaking workflow enhancement** and can be adopted incrementally. No impact on runtime behavior or existing APIs.
---
### References
* [https://www.conventionalcommits.org/en/v1.0.0/](https://www.conventionalcommits.org/en/v1.0.0/)
* [https://github.com/conventional-changelog/commitlint](https://github.com/conventional-changelog/commitlint)
* [Apache Airflow Commit Guidelines](https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst#commit-message-guidelines)
* [Apache Superset Commit Guidelines](https://github.com/apache/superset/blob/master/CONTRIBUTING.md#commit-messages)
### Describe the solution you'd like
### Proposed Format (with Examples)
Following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)] specification:
```bash
feat(parser): add support for query metadata filtering
fix(ui): correct tab rendering when resizing sidebar
docs: update README with configuration examples
refactor(core): simplify planner interface logic
chore: upgrade dependencies and clean up types
```
Example with a breaking change:
```bash
feat(api): refactor search API response format
BREAKING CHANGE: search API now returns a flattened result instead of nested hits
```
### Describe alternatives you've considered
### Implementation Plan
1. Add commit message guidelines to `CONTRIBUTING.md`.
2. Optionally add a commit hook using [[commitlint](https://github.com/conventional-changelog/commitlint)](https://github.com/conventional-changelog/commitlint).
3. Integrate changelog generation and semantic versioning into the release process (e.g., via GitHub Actions).
4. Encourage consistent commit messages via pull request templates and documentation.
### Additional context
_No response_
Contributor guide
Research direction
Start by reviewing CONTRIBUTING.md and the issue's Conventional Commits, commitlint, and GitHub Actions references. Define the project's agreed commit format and decide which parts of the proposed plan are in scope; done means the guidelines and any selected hook, changelog, or release-process automation are documented and adopted.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, github-actions
- Domain
- ci-cd, developer-experience, documentation, release
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100