incubator-bloodhound-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Apache Bloodhound" <>
Subject [Apache Bloodhound] BloodhoundDevGuide added
Date Thu, 20 Sep 2012 13:08:17 GMT
Page "BloodhoundDevGuide" was added by gjm
= Bloodhound Developer Guidelines =

== Coding Style ==
The coding style for Bloodhound is the [ PEP 8] standard.
Deviations from this coding style may be considered in submitted patches as readability is
considered more important.

== Ticket Work Guidelines ==
Discussion of defects (bugs), new or improved features (enhancements) and other tasks should
occur primarily on the ! 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
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
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 !
(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
If you do not wish to subscribe to, 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
list unless anyone thinks that discussion would be worthwhile.

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

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 message. Such a comment would be of this form:
     diff content
 2. Paste the patch into an email to bloodhound-dev in a reply to the ticket thread
and for larger changes:
 3. Upload the patch as an attachment to the ticket and reply to the resulting message in

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

==== 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

== 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. 

Page URL: <>
Apache Bloodhound <>
The Apache Bloodhound (incubating) issue tracker

This is an automated message. Someone added your email address to be
notified of changes on 'BloodhoundDevGuide' page.
If it was not you, please report to .

View raw message