Hi all, First of all, thanks for all your feedback. I have tried to incorporate all your comments and address your concerns. Please review the new guide for contributors, and the new pull request template, in the pull request
https://github.com/apache/ofbiz-framework/pull/2000 Best regards, Jacopo On Thu, May 28, 2026 at 9:27 AM Jacopo Cappellato <[email protected]> wrote: > > 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: > > Create a Jira ticket describing the change > > Create commits using the fixed format (including Jira references, categories, > etc.) > > Create a pull request (often repeating information already present elsewhere) > > Proposed workflow: > > Create one or more commits with a title and optional description using the > open format described above > > Submit a pull request using the pull request template (which we can improve > to provide better guidance) > > Optionally create a Jira ticket for bug reports or early design discussions > > I would be interested in hearing feedback from the community. > > Jacopo
