THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
"Being a committer does not [only 
] mean you commit code, it means you are committed to the project."
| Info | ||
|---|---|---|
| ||
After the svn tag "beforeSvnRestructuring" the repository structure has changed, please refer to history for information before this tag |
| Table of Contents |
|---|
The committers of OFBiz are those contributors who have the ability to commit changes into the OFBiz source code repository. As the project has grown over the years, The committers of OFBiz are a core group of developers who have the ability to commit changes into the OFBiz source code repository. As the project has grown over the years, there have been more committers of projects, so we thought it would be a good idea to define what the roles and responsibilities of the committers are. These points below are based on discussions we recently had on the developers' list:
...
- submitting new code
- reviewing patches (here is a good article about Code Review Best Practices)
- answering questions answering questions from the community
- reviewing/adding/improving documentation (in wiki or "inside" or even OFBiz, like books)
- helping on the marketing side
- etc. (you name it)
...
- Subscribe to the dev mailing list, try to read the majority of the messages, and participate in discussions there
- Review and comment on issues in the Jira issue tracker
- Apply patches from Jira locally and test them and comment on the results
- Create patches to fix issues reported in Jira
- Get to know OFBiz and submit patches to fix problems or annoyances you find
- Follow the advice and do all of this according to the recommendations in the Contributors Best Practices document
Committing Changes
When committing changes, all committers should follow these general guidelines:
- Committers should set up their SVN client to use the official OFBIZ Subversion client configuration file
- Committers should review contributions to ensure that they follow good coding standards, are well-commented and understandable, and follow our coding conventions
Committers should write a meaningful description of the feature being committed in the commit log so other developers and committers could understand what is happening.
Note title Here are some commit comments examples of badness taken from an Adam's message in dev ML - Fixed bug (reported by $user)? from $location.
When reading history, the full discussion leading up to a proper bug fix is not important. But a description of the bug, and the solution, are necessary.
Quite often, when trying to find a bug, the original sources are not available. All you have at your disposable is the installed system image. The changelog describing the software installed very often accompanies the installation. It's quite possible that no outside access is available. Embedded system deployments do this quite frequently.
When scanning a changelog for possible hints into why something is/isn't working, if I have to switch back and forth from the target system, and an external system, to figure out what is going on, then it will leave a sour taste in my mouth. Going forward, I would be reluctant to recommend the software again.
Additionally, no one is you. There are 6 billion other people on this planet, and you are the only one who knows what you are thinking. We can't read minds. It becomes even more difficult to do so, 2-3(or more) years in down the road. So, describe what you have done at the time you have done it.
Also, not everone knows how jira works. Or confluence. Or AutoConfigMaintenceWidgetApplication. What you may thing as a sensible cross-reference(OFBIZ-####, debbugs ####) may mean nothing to the person reading your changelog.
- I did some things in FooClass, FooImpl, some more stuff in BarWidget, and yet more interesting tidbits in YellowSubmarine; basically, stuff all over the place.
This bad changelog is not about poor descriptions of the changes. It's about listing multiple, 100% completely separate improvements/fixes into a single commit.
If there were 10 lines changed, and 1 line was not related, it's possible that you could still notice that 1 extra line. But if you have 1000 lines changes, and there are 3 groups of changes, and they are all intermingled, it becomes very difficult to verify that each separate change was actually implemented correctly.
It's much better to split up such changes, and commit them separately. There are several ways to do this. svk/hg/git can be used to mirror svn, have local changes, then push when you are done. You can use multiple svn checkouts, and redo your changes, one step at a time.
- Fixed bug (reported by $user)? from $location.
In addition, all committers must do the following to ensure licensing compliance:
- Make sure the contribution is posted publicly on the Apache OFBIZ JIRA issue tracker. Please do not commit changes that were sent to you privately. If you receive a patch, open a JIRA issue and then ask the submitter to post his patch there. This way, we can avoid having to get an iCLA for the contributor, as well as let everybody in the community view and comment on the contribution.
- If it is a new file, the file must have the Apache 2.0 license header.
- The commit log must identify the name of the contributor and, if relevant, the JIRA issue for it.
Following changes
Manage JIRA's issues
Please take the time to correctly fill the different Jira fields we now use for our releases change logs.
- Specifiy in Resolution :
- Improvements : use either Done or Implemented Status as you feel right
- New features : use the Implemented Status
- Bug : use the Fixed Status
| Info | ||
|---|---|---|
| ||
The OFBiz project will next release 2 products: the framework (which for now includes applications) and the plugins. It is the responsibility of committers to maintain both products. So committers should checkout the framework and include the plugins using the Gradle pullAllPluginsSource. It is the also responsibility of committers to help fellow contributors to achieve a successful resolution of issues in JIRA. Committers should try, as much as possible, to avoid that patch files submitted to issues grow stale. It is a waste of effort and precious time on the part of a fellow contributor when patches grow stale, as rework needs to be done. Timely evaluation of patch files prevents the need for rework and re-evaluation. Showing interest in the work of fellow contributors builds better relationships and a healty community. When doing so, an efficient rule of thumb for productivity is the Ten minutes rule: if you can commit a patch in less than 10 minutes then just do it! Of course don't do that all the day long. Another important responsibility of a committer is participating in voting, especially the ones for new releases.. |
When committing changes, all committers should follow these general guidelines:
- Use a SVN 1.8 or newer client. Because we use repo dictated config and no longer need the official OFBIZ Subversion client configuration file, at least for OFBiz (you might need it for other purposes...)
- When a committer adds a new file type, it must be put it as a svn:auto-prop at the OFBiz root level in ASF Subversion repo. Here is a commit example: http://svn.apache.org/viewvc?view=revision&revision=1840885
- Committers should review contributions to ensure that they follow good coding standards, are well-commented and understandable, and follow our coding conventions
- The commit message should follow the general Commit message template.
Committers should write a meaningful description of the feature being committed in the commit log so other developers and committers could understand what is happening.
Note title Here are some commit comments examples of badness taken from an Adam's message in dev ML - Fixed bug (reported by $user)? from $location.
When reading history, the full discussion leading up to a proper bug fix is not important. But a description of the bug, and the solution, are necessary.
Quite often, when trying to find a bug, the original sources are not available. All you have at your disposable is the installed system image. The changelog describing the software installed very often accompanies the installation. It's quite possible that no outside access is available. Embedded system deployments do this quite frequently.
When scanning a changelog for possible hints into why something is/isn't working, if I have to switch back and forth from the target system, and an external system, to figure out what is going on, then it will leave a sour taste in my mouth. Going forward, I would be reluctant to recommend the software again.
Additionally, no one is you. There are 6 billion other people on this planet, and you are the only one who knows what you are thinking. We can't read minds. It becomes even more difficult to do so, 2-3(or more) years in down the road. So, describe what you have done at the time you have done it.
Also, not everone knows how jira works. Or confluence. Or AutoConfigMaintenceWidgetApplication. What you may thing as a sensible cross-reference(OFBIZ-####, debbugs ####) may mean nothing to the person reading your changelog.
- I did some things in FooClass, FooImpl, some more stuff in BarWidget, and yet more interesting tidbits in YellowSubmarine; basically, stuff all over the place.
This bad changelog is not about poor descriptions of the changes. It's about listing multiple, 100% completely separate improvements/fixes into a single commit.
If there were 10 lines changed, and 1 line was not related, it's possible that you could still notice that 1 extra line. But if you have 1000 lines changes, and there are 3 groups of changes, and they are all intermingled, it becomes very difficult to verify that each separate change was actually implemented correctly.
It's much better to split up such changes, and commit them separately. There are several ways to do this. svk/hg/git can be used to mirror svn, have local changes, then push when you are done. You can use multiple svn checkouts, and redo your changes, one step at a time.
- Fixed bug (reported by $user)? from $location.
| Warning | ||
|---|---|---|
| ||
Patches should never be used to move files. The diff and patch commands (even "svn di" and "svn patch") are unable to keep the information about moved files, only deleted and created. So we must not apply patches with files relocations. We not only lose history when doing so, but also annotations |
All committers must do the following to ensure licensing compliance
- Make sure the contribution is posted publicly on the Apache OFBIZ JIRA issue tracker. Please do not commit changes that were sent to you privately. If you receive a patch, open a JIRA issue and then ask the submitter to post his patch there. This way, we can avoid having to get an iCLA for the contributor, as well as let everybody in the community view and comment on the contribution.
- If it is a new file, the file must have the Apache 2.0 license header.
- The commit log must identify the name of the contributor and, if relevant, the JIRA issue for it.
Type of changes and where should they go
There are roughly 3 main types of changes:
- New features
- Improvements
- Bug fixes
Bug fixes should normally go in the release branches, as much as they can. Security fixes must trigger a new released packages.
New features and Improvements should never get into a release branch. Exceptions may occur, but they need a consensus, and as ever can be vetoed (only by committers, though this rule can be adapted by the community)
How should committers handle backporting?
- Only bugfixes should be backported to active release branches (if they happen also there).
- Bugfixes should be backported by the committer who did the bugfix in trunk, if possible.
- If the committer does not, for a reason, backport the bugfix, he should leave the original issue open with a remark that a backport is needed and a short explanation why he does not do the backport.
- Issues that need a backport should be labelled as "backport-needed". In this way we are able to spot issues to be backported, especially before a release is on it's way.
- In no case should the Jira issue be closed without doing 1. or 2.
- When you backport something, if you know that it should not be backported in older releases, please pass the information.
Christian Carlow asked
Should committers download the entire ofbiz repository to help with backporting?
Here is Jacopo Cappellato's answer:
It is easier if you keep the trunk and the release branches in different svn folders (i.e. different checkouts); for example:
mkdir ofbiz cd ofbiz svn co http://svn.apache.org/repos/asf/ofbiz/ofbiz-framework/trunk svn co https://svn.apache.org/repos/asf/ofbiz/branches/release14.12 svn co https://svn.apache.org/repos/asf/ofbiz/branches/release13.07 svn co https://svn.apache.org/repos/asf/ofbiz/branches/release12.04 svn co https://svn.apache.org/repos/asf/ofbiz/site
You will end up with the following folder layout:
ofbiz/
ofbiz/trunk
ofbiz/release14.12
ofbiz/release13.07
ofbiz/release12.04
ofbiz/siteIs there a standard procedure new committers should follow for backporting?
Here is a simple workflow to backport a commit to a branch.
1) commit the fix to trunk and note down the commit id; e.g. rev 12345 2) go to the release branch you want to backport to; e.g. cd ofbiz/release14.12 3) run the following script (the script will apply the commit to your local release branch): ./tools/mergefromtrunk.sh/bat merge 12345 4) run the tests with: ./tools/mergefromtrunk.sh/bat test 5) it is also a good idea to start the instance and test manually 6.a) if tests are unsuccessful, abort the process and clean your local release branch: ./tools/mergefromtrunk.sh/bat abort 6.b) if tests are successful, and you want to commit the backport: ./tools/mergefromtrunk.sh/bat commit
Handling deprecated services
We tag deprecated services as a part of a release branch using the "<deprecated" element. Deprecated services will be removed from the next release branch when this new branch is created.
Lets say we set a service as deprecated for release branch R18. This service will be part of R18 and will be removed in next release branch R19.
For instance, imagine we decide to create a next to be released R19 branch.
We have on trunk :
- addCatalogMember deprecated since="Upcoming Branch"
- deleteWorkEffortAssignment deprecated since="18.12"
When we create the R19 release branch, we change on trunk :
- addCatalogMember deprecated since="19.xx"
- deleteWorkEffortAssignment deprecated since="18.12"
Before creating the new R19 branch we remove the services deprecated since R18. So the trunk contains only:
- addCatalogMember deprecated since="19.xx"
On this basis we create the R19 branch.
An so on...
Following changes
Manage JIRA's issues
To avoid confusion with other committers, when you take in charge a JIRA with a ready patch (Provide Patch button has been pushed) you should assign it to you and push the Start Progress button.
Please take the time to correctly fill the different Jira fields we now use for our releases change logs.
- Specifiy in Priority: much of the time you can pick what seems to fit. Beware that the default is Major and it does not always fit. As a committer don't hesitate to change the priority if it was set by a contributor and does not respect the rules below.
- The Blocker priority can be used when something really blocks OFBiz to start, so it should rarely be used. There are certainly other cases where it can be used, notably when an issue blocks a release.
Critical - A feature of critical importance is faulty. A workaround is possible, or a quick fix could be applied after release. While you usually would not release with a critical fault present, it's conceivable.
- Specifiy in Resolution :
- Improvements : use either Done or Implemented Status as you feel right
- New features : use the Implemented Status
- Bug : use the Fixed Status
- Of course you might also use other status (like duplicate, won't fix, invalid, etc.) when needed...
- Specify in Affects Version/s: pick the version/s which is/are affected
- Specify in the Fix Version/s the codebase(s) to which you have committed the patch/fix. Please don't set the "Fix Version/s" before closing, only the "Affects Version/s".
- you can select from the dropdown one or more of the
Specify in the Fix Version/s the codebase(s) to which you have committed the patch/fix :- items under the "Unreleased Versions" group in the top part of the drop down box;
- you should never
use one of the items in the "Released Versions" section (bottom part); if the fix/patch is submitted to "Trunk" then select "Upcoming Branch"- use one of the items in the "Released Versions" section (bottom part);
- if the commit is only done on "Trunk" (ie not backported) then select "Upcoming Release". For an improvement or a new feature only the "Upcoming Release" version must be used because it's the only possibility offered to you. I think it's good to set even before closing so that nobody will use a wrong version there see this thread;
- if you are backporting/committing to a release branch then select the latest (next) release version in that branch available in the dropdown. No needs then to put also "Upcoming Release", it's implied.
you can select from the dropdown one or more of the
For example at the moment the valid items for the Fix Version/s field are :
- 16.11.05 (for commits to the branch named release16.11)
- 17.12.04.0601 (for commits to the branch named release12release17.0412)
- 13.07.02 (for commits to the branch named release13.07) Upcoming Branch (for commits to trunk)
- Upcoming Branch (only for commits only done to trunk, ie when not backporting)
| Info | ||
|---|---|---|
| ||
| As per our conventions, when the reporter or the assignee, or even another person who has reviewed, decides the issue is implemented, done or fixed (or any other resolution type) the issue should be CLOSED. |
After some time the following Jira reports will contain very useful information :
- Road Map (what is expected in upcoming releases) : https://issues.apache.org/jira/browse/OFBIZ/?selectedTab=com.atlassian.jira.jira-projects-plugin:roadmap-panel
Change Log (what is available in released packages available from the Download page) : https://issues.apache.org/jira/browse/OFBIZ/?selectedTab=com.atlassian.jira.jira-projects-plugin:changelog-panel
Note title Reminder If the svn commits comments are correctly done, with a reference to the Jira issue number, we can then get to the commits in Fisheye from the Development section of the Jira issue.
Also, please put the revision number in the Jira issue. That helps others doing research on changes.
Complete the documentation
...
- what is expected in upcoming releases) :
Change Log (what is available in released packages available from the Download page, this is not to be confused with the information given in our monthly blog posts)
Note title Reminder If the svn commits comments are correctly done, with a reference to the Jira issue number, we can then get to the commits in Fisheye from the Development section of the Jira issue. These can take a few days though...
Also, please put the revision number in the Jira issue. That helps others doing research on changes.
Complete the documentation
- Of course it's recommended to follow what's going on on MLs, especially dev ML.
- Following changes on wiki is also recommended, one way is to subscribe to the daily email changes (in your Preferences/Watches). If you don't want to see anything about other projects you may only watch OFBiz spaces
OFBiz (Open For Business) Project Open Wiki
OFBiz End-User Documentation
OFBiz Project Administration Workspace
OFBiz Requirements and Designs
OFBiz Technical Documentation
You will be then alerted about any changes just after they have been done (with links)
Using Buildbot
Here is a small documentation whith most aspects to know
Code of conduct
The ASF has a Code of conduct, it's good to know and remember it. Though for miscellaneous reason you become a committer for life, please note this: "When somebody leaves or disengages from the project they should tell people they are leaving and take the proper steps to ensure that others can pick up where they left off."
...