Create Ticket
Warning Can't synchronize with repository "(default)" (/x1/svn/asf/bloodhound does not appear to be a Subversion repository.). Look in the Trac log for more information.
Last modified 4 years ago Last modified on Mar 27, 2013 5:16:02 PM

Bloodhound Developer Guidelines

Coding Style

The coding style for Python within the project is the PEP 8 standard. Deviations from this coding style may be considered in submitted patches as readability is considered more important.

To help spot deviations from appropriate style, committers can use the pylint tool to search for problems. If you are working in a virtualenv, running the following in your activated environment will install it:

pip install pylint

Pylint provides a lot of output that is probably of little importance. On unix like systems it is possible to put the following into your home directory's .pylintrc file to remove some of that excess:

[MESSAGES CONTROL]
# C0103 = Invalid name
# R0201 = Method could be a function
# R0903 = Too few public methods
# R0904 = Too many public methods
# R0912 = Too many branches
# R0913 = Too many arguments
# R0914 = Too many local variables
# W0142 = Used * or ** magic

disable=C0103,R0201,R0903,R0904,R0912,R0913,R0914,W0142

[TYPECHECK]
generated-members=log,env

Ticket Work Guidelines

Discussion of defects (bugs), new or improved features (enhancements) and other tasks should occur primarily on the dev@bloodhound.apache.org mailing list. It is therefore essential that you are subscribed to this list. In general, to work on an Apache Bloodhound ticket, you would also be expected to have an account on this issue tracker so that a ticket can be assigned to you, discouraging others from duplicating your effort.

Raise Then Discuss/Discuss Then Raise

For new functionality it might be more usual to discuss the issue on dev@bloodhound.apache.org first and possibly create a wiki page to document new functionality and designs.

For defects, it is fine to raise a ticket and then start a discussion on dev@bloodhound.apache.org or raise a ticket as a result of a discussion. Both the ticket and the discussion should exist for work to commence.

Creating Tickets

In creating a ticket you should attempt to provide a short summary.

  • For enhancements and tasks it is usually better for the summary to be framed to suggest an action that has to be performed
  • For defects it is fine to just summarise the bug that has been found as the 'fix this' is implied

The ticket type should be set appropriately:

  • Tasks are usually non-coding related work items (site updates, suggested discussions other projects, ...)
  • Defects are bugs in the code or deviations from behaviour that is meant to be implemented.
  • Enhancements are new pieces of functionality or suggested improvements to existing functionality.

Similarly, the component should reflect the area of work that seems most relevant.

Ticket descriptions should be clear and have enough information for someone other than the author of the ticket to take it on.

It is generally better to avoid specifying a milestone or raising the priority above the default (major) unless there seems to be a good justification. An Apache committer on the project should attempt to set an appropriate milestone and priority. This does not mean that a low priority ticket or a ticket outside of the current milestone has to be ignored by all developers; patches may be accepted against such tickets if it is considered appropriate. Apache committers on the project will generally be expected to work on tickets within the current active milestone.

Creating a Ticket Discussion

If a ticket already exists, and you are subscribed to commits@bloodhound.apache.org (strongly recommended), you will receive an email as a result of most ticket change events. Replying to one of these will send your resulting email to dev@bloodhound.apache.org. If you do not wish to subscribe to commits@bloodhound.apache.org, or you do not want to reply to such a message, at the bare minimum you should write an email with the #ticketnumber specified in the subject and preferably include a link to the ticket under discussion. Preferably the subject should also include part of the title of the ticket to make it a little easier to see what the ticket is about.

Working on the Ticket

Once the ticket is understood well enough by the assigned developer to attempt to write code to satisfy the requirements, the developer should accept the ticket. If the developer feels that the work is mis-assigned, reassignment to 'nobody' is acceptable. A comment on why on the ticket would also be helpful. This is also possible after acceptance of a ticket if the developer feels that they are unable to complete the ticket. On the other hand, developers should feel that they can ask for help and opinions to gain the knowledge to get them through any barriers.

As work progresses on the ticket, appropriate observations and progress should be noted as comments in the ticket. Such comments do not have to be brought to the attention of the dev@bloodhound.apache.org list unless it is something that requires discussion.

The work that is done in the ticket should never expand to do work listed in another ticket. If it turned out that the current ticket depended on the other ticket, it would be better to put the current ticket on hold. If the other ticket is a clear duplication, one of the tickets should be closed with the 'duplicate' resolution. This may require negotiation between developers, particularly if both tickets are in progress. If both tickets require a non-ticketed common functionality then there is a choice of raising another ticket to provide the common code or noting the overlap in the tickets and providing the functionality in one of them to be used in the other.

More generally, expanding the scope of a ticket should be avoided. If there is an obvious item of work that naturally arises, a new ticket should be created instead. On the other hand, creating more tickets to further divide up work from an existing ticket will probably be fine as long as relationships between tickets are stated. Tools to track inter-ticket dependencies may be expected to be added to help with this.

When coding, a developer should make sure that they are starting from an up-to-date checkout of trunk.

Submitting Code

Trunk should always remain buildable and so code that is expected to break Bloodhound must be avoided. At worst, any break should be expected to be corrected extremely swiftly.

Smaller changes that meet this criterion are preferred to make it is easier to see progress on a ticket over time and make it easier for the code to be reviewed.

As Patches

For developers who are not Apache committers, it is only possible to contribute code through patches.

There are three ways that patches can be provided:

For smaller changes:

  1. Paste the patch into a ticket, and follow it up with a reply to the email from the resulting commits@bloodhound.apache.org message. Such a comment would be of this form:
    {{{
    #!diff
    diff content
    }}}
    
  2. Paste the patch into an email to bloodhound-dev in a reply to the ticket thread

and for larger changes:

  1. Upload the patch as an attachment to the ticket and reply to the resulting message in bloodhound-commit@…

A good description of what the patch is for and a note of which revision it was built against (you did check that it would apply against the HEAD of trunk, didn't you?) would be particularly useful.

As svn commits

Any commits against the code should include an appropriate, generally single lined, commit message which specifies the #ticket number. For example:

svn commit -m "changed this thing to do that - towards #1"

Upon committing, the reported revision number should be added to a ticket comment, preferably along with another description of the commit. Repeating the commit message is not unreasonable and fairly easy but providing an alternate explanation to the commit message can also be helpful, particularly if more detail seems appropriate.

It is also allowed and even encouraged to group a number of changeset comments into a single comment with as much detail as you feel is appropriate as long as there is not a large delay between the first commit and the last in the set.

References to commits made in comments should use either the [12345] or r12345 syntax which (at least in the near future) will create links to changeset views in Bloodhound's source browser.

Identifying Starter Tickets

If a ticket describes a small piece of work that seems ideal for a new starter to get acquainted with relatively little knowledge of the project, adding 'starter' to any list of keywords will help new developers identify tickets that they may wish to consider. In general these should not be expected to be high priority tickets as it may not be helpful to put such pressure on a potential contributor while they are finding their feet and trying to work out how much time they might be able to commit.