Why You Should Contribute to OFBiz
...
There are, at least, two kind of contributors: bug reporters, and plain contributors (the ones who follow these Contributors Best Practices). If you don't have enough time or competence to solve a bug by yourself, you may simply report it on the user MLmailing list. But then please respect the conventions above.
| Tipnote |
|---|
| title | How When to create a Jira issue |
|---|
|
- Create an account here, if you do not have one
- Login
- (optional if you are sure it's new) Search if an issue for what you are after already exists by using the "Find issues"
- (optional if you are sure it's new) If an issue on the subject already exists you can add a comment on it
- If a issue does not exist, create a new one selecting the "create new issue" command. For details on the issue creation see here
- Select the OFBiz project and the issue type.
- Fill in all fields, give as many detail you think necessary
- Generally it is very important to select in the "Affect version" field the ofbiz version you are running. If you are running the trunk then the SVN revision should also be specifyed in the Environment field
- Use the Environment field to specify at least your operating system and the database ofbiz is using since these information could be very useful to help people to work on the issue
- Select the concerned component(s). If all components are affected select ALL_COMPONENTS (uncommon case)
- If you need to attach files such as patches you must do it as a second step after the issue creation. It is also possible to easily attach screenshots to the issue see here
- When attaching files or screenshots you can add a comment where you explain how the attached file is supposed to be used. Please reference the file name in the comment because more files could be attached to the issue at a later time and they will be all listed togheter far from their comments. If, for any reason, you don't want your patch or attachment to be granted to the ASF or committed, please note it in one related comment (possible cases: not ready yet, examples, etc.)
- Also please use preferably .patch as extension for patches. When updating an attached file keep the same name : Jira is able to deal with that and will simply gray old files, you don't need to delete them (sometimes its usefull to compare older patches versions)
- If you provide a patch, be sure to use the button "Provide Patch" (the status will then be "Patch Available"). This allows us (commiters) to know that this issue is ready for review.
- Jira offers a voting mechanism that is used to give more relevance to the issues (see here to learn more)
|
- Before creating any Jira issue, please check, using some related key words, if a similar issue does not exist already. For that you can first use the quick search at top right of Jira pages and after refine your search using relevant information. For instance by default all projects are scanned, you may then search only in OFBiz, etc.
- When you find a duplicate of a JIRA issue, please close the newer one with the resolution 'Duplicate', and state what the original issue is. This does not apply for placeholder issues or if the newer Jira does contain additional aspects or more comprehensive solutions, documentation or patches. If in doubt, please discuss on the development mailing list before choosing one issue over the other.
- If you already have a patch for an improvement/fix then create a Jira issue (if there is not one already) and attach your patch to it.
- If you don't have a patch, and you have discovered a bug, create a Jira issue (if there is not one already) providing as much details as possible (including the rev. number and the environment you are using, and the step to recreate the bug). if you have no ideas how to describe the bug use this template:
- What you did (including detailed steps to reproduce);
- What you expected to happen;
- What actually happened (including exact quotes of error messages, etc);
- If possible provide an URL from one of our demo sites.
- If you don't have a patch, and you have want to suggest an enhancement or new feature, then discuss this in the dev mailing list instead of creating a Jira issue; at the end of the discussion, the community will consider if a summary of the thread should be saved in a new Jira issue, to facilitate future development.
- If you don't have a patch, but you are planning to work on it, and you want to share your design details with the community, you should discuss this in the mailing list instead of creating a Jira issue; if, on the other hand, you don't have time to do this, you have already decided that you want to implement your patch following your design notes, and you just want to let the community know about the upcoming patch, you can create a Jira issue (to which you will attach your patch when it is ready);
Summarizing:
- Bugs: always create a new Jira issue everytime you find a new bug
- New features/enhancements: create new Jira issue only if you have a patch (or if you plan to submit it very soon).
|
How to create a Jira issue
| Tip |
|---|
| title | How to create a Jira issue |
|---|
|
- Ask for an account on the OFBiz user ML, if you do not have one.
- Login
- (optional if you are sure it's new) Search if an issue for what you are after already exists by using the "Find issues"
- (optional if you are sure it's new) If an issue on the subject already exists you can add a comment on it
- If an issue does not exist, create a new one selecting the "create new issue" command. For details on the issue creation see here
- Select the OFBiz project and the issue type.
- Fill in all fields, give as many details as you think necessary
- If you need to attach files such as patches you must do it as a second step after the issue creation. It is also possible to easily attach screenshots to the issue see here
- When attaching files or screenshots you can add a comment where you explain how the attached file is supposed to be used. Please reference the file name in the comment because more files could be attached to the issue at a later time and they will be all listed together far away from their comments. If, for any reason, you don't want your patch or attachment to be granted to the ASF or committed, please note it in one related comment (possible cases: not ready yet, examples, etc.)
- Also please use preferably .patch as extension for patches. When updating an attached file keep the same name: Jira is able to deal with that and will simply gray old files, you don't need to delete them (sometimes its useful to compare older patches versions)
- If you provide a patch, be sure to use the button "Provide Patch" (the status will then change to "Patch Available"). This allows us (committers, and other contributors) to know that this issue is ready for review.
- Jira offers a voting mechanism that is used to give more relevance to the issues (see here to learn more).
|
| Info |
|---|
| title | How to work with Confluence (by order of preference) |
|---|
|
- If you are a registered wiki contributor (recommended) you can edit any page in the wiki, just be sure to add a sentence about what you did when committing.
- If you are not a registered wiki contributor and don't want to be one, you can still add your Confluence formatted contents as comments in existing pages. So if you need a new page you need to ask for its creation before adding comments...
- If you don't want to provide Confluence formatted user stories then open a Jira and add your unformatted user stories in a text file
|
| Note |
|---|
| title | When to create a Jira issue |
|---|
|
- Before creating any Jira issue, please check, using some related key words, if a similar issue does not exist already. For that you can first use the quich search at top right of Jira pages and after refine your search using relevant information. For instance by default all projects are scanned, you may then search only in OFBiz, etc.
- If you already have a patch for an improvement/fix then create a Jira issue (if there is not one already) and attach your patch to it
- If you don't have a patch, and you have discovered a bug, create a Jira issue (if there is not one already) providing as much details as possible (including the rev. number and the environment you are using, and the step to recreate the bug). if you have no ideas how to describe the bug use this template
- What you did (including detailed steps to reproduce)
- What you expected to happen
- What actually happened (including exact quotes of error messages, etc)
- If possible provide an URL
- If you don't have a patch, and you have want to suggest an enhancement or new feature, then discuss this in the dev mailing list instead of creating a Jira issue; at the end of the discussion, the community will consider if a summary of the thread should be saved in a new Jira issue, to facilitate future development
- If you don't have a patch, but you are planning to work on it, and you want to share your design details with the community, you should discuss this in the mailing list instead of creating a Jira issue; if, on the other hand, you don't have time to do this, you have already decided that you want to implement your patch following your design notes, and you just want to let the community know about the upcoming patch, you can create a Jira issue (to which you will attach your patch when it is ready);
Summarizing:
Bugs: always create a new Jira issue everytime you find a new bugNew features/enhancements: create new Jira issue only if you have a patch (or if you plan to submit it very soon)
|
Following changes
Please read this section in OFBiz Committers Roles and Responsibilities page
...
| Tip |
|---|
|
- Follow coding conventions. Seriously, read that document.
- Install the OFBIZ OFBiz Subversion client configuration file
- Follow the 2 main rules for committers:
- Rule #1 for a committer is the same as for a doctor: first do no harm. Nothing should be committed that breaks existing functionality without replacing it either before or in the same commit. Whatever you are working with someone developed it and chances are someone is using it, and possibly MANY people.
- Rule #2 for a committer is the same as for a scientist: read before you write. When you're getting started a good time ratio for read to write is around 20 to 1. Once you're a total OFBiz pro who knows as much as any living person about the project, you can probably reduce that to about 3 to 1.
- Discuss your features with the community. What are you trying to implement, and how are you planning to do it? This is especially important if you are new to the project.
- Write clear, well-commented, and understandable code. Don't take shortcuts, especially around variable names and error or warning messages. Use understandable data structures. Remember, somebody else will be working with your code down the road.
- When you prepare a patch, do your best to avoid to mix mixing formatting changes with relevant changes (if possible, provide a separate patch containing only formatting changes): in this way, the reviewer's work will be easier
- When you prepare a patch, do not insert in the code comments with author information since your name will be recorded in the commit log (that is the place were we store this kind of information)
- Internationalize your code with UI labels.
- Start out with small contributions which are easier to review. In the process, get familiar with the project's coding style and "thought process."
- Keep patches and contributions easy to review and commit. Even if a lot of code is touched, try to keep things isolated and the intent of the patch(es) clear. Remember that most committers can find 20 minutes here and there, but it is very hard to fit in the 2-4 hour time block required to review and commit a larger patch (especially if it touches ANY lower level or more sensitive or complex artifacts, and this requires more thorough review).
Also, try to give commiters committers enough information to quickly test your patches if it's a bit complex- For instance, steps to test
- If possible an URL, it's always helpful
- Put your contributions on JIRA instead of emailing it directly to the committers, so everybody can review and comment on it. Though it is not necessary this makes contributions more traceable for the licensing through the Apache Software Foundation.
- Get other members of the community to try your patch. Write the dev list and tell them what you've done and ask them to try it out and vote for it. This will help the committers when they are reviewing your patches as there will be more confidence confident that the patch does what it is intended to do, and doesn't break anything else.
|
...
| Note |
|---|
| title | Naming entities and their fields |
|---|
|
Here are some conventions, or say patterns, which are common for defining an Entity and its Fields. - Entity names must be in UpperCamelCase.
- Entity names must be short enough so that the automatic table name (with an underscore added before each capital letter) is 30 characters or less.
- Field names must be short enough so that the automatic column name (with an underscore added before each capital letter) is 30 characters or less.
- fk-name should not must be more then 18 letterscharacters or less.
- If entity name is abbreviation like Unit Of Measure (UOM) then treat it as one word, like: Uom.
- The Field field name must be in lowerCamelCase and the name should be self descriptive enough to show the purpose of the field.
- If relation tag specify the relationship between two entities then the fk-name should contains the words from both entities separated by ("_") underscore.
- If a entity relation with another entity defines more than one time then it should be differentiated by title attribute while defining a relation like "FormFrom" or "To".
- In the same if both fields in the <key-map> tag are the same, then there is no need to specify the rel-field-name.
- In case of view entities the name will must consist of names of all its member entities.
- The <view-link> should be define defined for proper view in the webtools.
|
...
How to
...
send in
...
your contributions (or how to create
...
patches, even with Git)
The first step is to create an account for yourself on the JIRA issue tracker and then create a new issue. Describe the contribution that you are making: are you fixing a bug, improving an existing feature, or creating a new feature? Please write as detailed a description as you can and attach screenshots if possible of what you've done. OFBIZ is a huge project, and what may be obvious to you might not be to someone else, even a committer who is familiar with the project.
...
- Command line (see the howto below)
- Eclipse internal command (don't use finish but rather select project to avoid the 2 1st lines in the patch)
- A tool like TortoiseGit-UI client, like SourceTree, Tortoise, etc.
- If you use Git to create you patch please use "git diff --no-prefix" option to create it.
| Warning |
|---|
| title | No patches when moving files |
|---|
|
Patches must never be used to move files. Else if applied we not only lose history when doing so, but also annotations.
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 if you are moving files, simply create patches if some files refer to the paths of the relocated files (and hence need to be changed) and tell the committers which files should be moved (from -> to) |
...
| Warning |
|---|
| title | Trailing white spaces |
|---|
|
Please adjust your IDE or similar to not remove trailing white spaces when you create a patch, especially a big one, you may do that temporarily. Consider that else reviewers have to be confronted with a lot of false changes, thanks! |
We prefer that you build your patch from the root as it's easier for commiters committers to merge your change. So please make your patch files from the OFBIZ_HOME directory (usually ofbiz/) and with relative file paths.
"Relative file paths" means tha the in your patch file names should look like these :
applications/party/widget/partymgr/PartyScreens.xml
framework/webtools/config/WebtoolsErrorUiLabels.properties
and should not have file names like: C:\myfiles\ofbiz\applications\party\widget\partymgr\PartyScreens.xml
Exemples Examples using command line:
| Code Block |
|---|
svn di applications/product > OFBIZ-number_featureDescription.patch
|
...
Next upload your patch file to your JIRA issue. Please use .patch as extension, some tools use extensions and this facilitates commiters committers works.
Finally, if there are several patch files already on an issue, please write a comment about which file should be used. A best practice is also to keep the same filename if a patch file is updated. Jira will take care of that and will keep (better for history) but gray deprecated files with the same filename. It's easier for commiter committer to see at 1st glance which file to use. You can read in 1st comment below what may happen when not using the same filename.
When a Jira issue is totaly totally resolved, we prefer to close the issue than to put it as resolved. There are some cases where there is a tentative resolution and you don't want to close the case because you want the reporter or someone to review and test the fix to make sure it was what was intended. If it is a simpler issue and especially if you are the reporter, then it is best to just close it right away rather than coming back to it later to close.
...