Child pages
  • OFBiz Contributors Best Practices

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add instructions to add GoodForNewContributors label while creating a Jira

...

Tip
titleHow to create a Jira issue
  1. Create an account here, if you do not have one
  2. Login
    1. (optional if you are sure it's new) Search if an issue for what you are after already exists by using the "Find issues"
    2. (optional if you are sure it's new) If an issue on the subject already exists you can add a comment on it
  3. If a an issue does not exist, create a new one selecting the "create new issue" command. For details on the issue creation see here
  4. Select the OFBiz project and the issue type.
  5. Fill in all fields, give as many detail details as you think necessary
    • Generally, it is very important to select in the "Affect version" field the OFBiz version you are running.
    • Use the Environment field to specify at least your operating system and the database your OFBiz implementation is using, since these this information could be very useful to help people to work on the issue. If you are using the trunk branch for your development then the GIT commit ID should also be specified in the Environment field.
    • Select the concerned component(s). If all components are affected select ALL_COMPONENTS (uncommon case)
    • Leave the "Fix Version/s" field empty, unless you are adding something new (Improvement or New Feature) then "Upcoming Release" is fine. This field will be used by committers to specify the future release that will contain the fix.

    • Add "GoodForNewContributors" label if you think that it can be a good fit for a new contributor
  6. 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.
  7. Jira offers a voting mechanism that is used to give more relevance to the issues (see here to learn more).

...

Tip
titleGuidelines
  1. Follow coding conventions. Seriously, read that document.
  2. Install the OFBiz Subversion client configuration file
  3. Follow the 2 main rules for committers:
    1. 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.
    2. 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.
  4. 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.
  5. 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.
  6. 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
  7. 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)
  8. Internationalize your code with UI labels.
  9. Start out with small contributions which are easier to review. In the process, get familiar with the project's coding style and "thought process."
  10. 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 committers enough information to quickly test your patches if it's a bit complex
    1. For instance, steps to test
    2. If possible an URL, it's always helpful
  11. 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.
  12. 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.

...