Hi Jacopo,
thanks for your elaborate proposal.
afaik the mentioned contribution workflow in [1] was never the official
version. I think that was [2]. We had some discussions in the past about
them...
Anyway, I'm in favour to streamline all those informations under [3] and
make it easier for contributors to provide their contributions and find
decent documentation about the process.
The contributing documentation you provided in [4] is clear and
understandable and I like that. But it seems to move away from the Jira
based process and I see some drawbacks in it.
For topics which need conceptual work, discussions or structure to split
bigger tasks into subtasks (like in [5] or maybe upcoming bigger tasks
to refactor the framework), an issue based approach seems to fit better
in my view. I fear only having pull requests will make it harder to
manage those tasks. If I understand it right, having the Jira issue
number in the pull request title is needed to make them automatically
linked together, right?
The commit message template was a step forward to have more formal
commit messages with the idea to be able to parse them and use them as
base information for the blog. It would be great if we find a solution
where we can still compile changelogs, release notes etc. with reference
to more detailed information like in Jira or pull requests.
(we still have a Hugo based Apache OFBiz website nearly finished in our
git repo which would allow to have a blog again so I'm interested in
keeping those informations).
So, I like the idea to make things easier and clearer but also have some
doubts about the proposed steps.
Hope I explained it well enough and like to hear your thoughts about it.
Thanks and best regards,
Michael Brohl
ecomify GmbH - www.ecomify.de
[1]
https://cwiki.apache.org/confluence/display/OFBIZ/Contributing+via+Git+and+Github
[2]
https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
[3]
https://cwiki.apache.org/confluence/display/OFBIZ/Apache+OFBiz+Contribution+and+Development
[4]
https://github.com/jacopoc/ofbiz-framework/blob/contributing/CONTRIBUTING.md
[5] https://issues.apache.org/jira/browse/OFBIZ-11328
Am 28.05.26 um 09:27 schrieb Jacopo Cappellato:
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
