Hi all, I would like to propose updating our contribution workflow and commit message guidelines to simplify contributions and improve the quality of our git history, pull requests, and release notes.
Today, commit message guidelines are defined here: https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+commit+message+template and they are also the basis of our GitHub pull request template. The broader contribution workflow is documented here: https://cwiki.apache.org/confluence/display/OFBIZ/Contributing+via+Git+and+Github. While useful, this document is quite long and includes a lot of generic git information that is not specific to OFBiz. My main concern with the current commit message template is that it is very OFBiz-specific and enforces a fixed format that does not always fit the nature of the change. Instead, I would propose adopting a simpler and more open format based on widely used git best practices: a commit message should contain a title (imperative form, no trailing period) describing the change and an optional description separated from the title by an empty line. This approach is natural because it is already broadly adopted across many open source communities and tooling ecosystems. I would also suggest avoiding references to Jira tickets or external resources directly in commit messages: our source code and commit history are long-term project assets and should remain independent from external systems that may change or disappear over time. The current commit message template could instead become the pull request template. Pull requests are a more natural place for references to Jira tickets, related pull requests, external resources, design discussions, etc. The pull request title is also important because it can be used to automatically generate release notes. Regarding release notes, I propose generating them automatically from pull requests using GitHub tooling rather than Jira tooling. This makes pull requests the primary entry point for contributions and their documentation, instead of always requiring contributors to first create a Jira ticket. When contributors already have working code to contribute, opening a pull request and discussing details there is often more natural. Jira would still remain useful for bug reports without patches or when contributors want to discuss ideas and designs before implementation. All the information about this workflow could be documented in the CONTRIBUTING document already present in the repository and expanded to describe the new process. This would allow contributors to immediately find the guidelines directly in the repository instead of having to search through Confluence documentation. A first draft of such document is already available here: https://github.com/jacopoc/ofbiz-framework/blob/contributing/CONTRIBUTING.md In practice, the workflow would become: Current workflow: 1. Create a Jira ticket describing the change 2. Create commits using the fixed format (including Jira references, categories, etc.) 3. Create a pull request (often repeating information already present elsewhere) Proposed workflow: 1. Create one or more commits with a title and optional description using the open format described above 2. Submit a pull request using the pull request template (which we can improve to provide better guidance) 3. Optionally create a Jira ticket for bug reports or early design discussions I would be interested in hearing feedback from the community. Jacopo
