Page "BloodhoundDevGuide" was added by gjm Content: -------8<------8<------8<------8<------8<------8<------8<------8<-------- = Bloodhound Developer Guidelines =
== Coding Style == The coding style for Bloodhound is the [http://www.python.org/peps/pep-0008.html 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 [email protected] 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 [email protected] 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 [email protected] 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 [email protected] (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 [email protected]. If you do not wish to subscribe to [email protected], 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 [email protected] 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 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 [email protected] 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: 3. Upload the patch as an attachment to the ticket and reply to the resulting message in [email protected] 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. -------8<------8<------8<------8<------8<------8<------8<------8<-------- -- Page URL: <https://issues.apache.org/bloodhound/wiki/BloodhoundDevGuide> Apache Bloodhound <https://issues.apache.org/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 .
