[CONF] Apache Qpid > Qpid Project Developers' Guide

[confluence]

Qpid Project Developers' Guide Page edited by Phil Harvey Changes (46) h2. Purpose This guide, written by Rafael Schloming, gives both Qpid committers and submitters a useful introduction to project etiquette, shedding light on how we do things & why. Following this etiquette makes the path to righteousness less long and winding ! This page describes how we do things and why. It includes guidelines on communication, collaboration and design. This guide was originally written by Rafael Schloming. h2. Maintainers h2. Tell others what you're working on The Qpid project consists of a number of major components spread across almost as many different languages. Thus it is rare for qpid committers to be experts in every single area of the project. As such it is expected that qpid committers make some effort to reach out to their teammates before directly modifying components that are outside their chosen areas. You should use the dev list to reach out to Qpid developers and comment on any JIRAs you're progressing. h2. Patch Submission h2. How to submit and apply patches As a committer it can be difficult to decide whether/how to provide feedback when someone submits a patch. Often it is tempting to just fix up the patch and avoid the slower and sometimes awkward process of telling someone that they got some part of it wrong. However, it is necessary to ensure that those who submit patches get to learn what they need to know in order to become a valued qpid committer. In that spirit, here are a few guidelines for contributing patch submissions and how we handle them: * Submitters should produce the final patch(s) as applied to the tree. Producing a patch that needs little or no rework is a key skill for a qpid committer. * Maintainers may make requests for 'trivial' updates to the patch. Such requests are vital to ensuring that contributers get familiar with subtle yet important aspects of the code, stylistic conventions, etc. * Make sure the submitter is familiar with project etiquette so they understand why we make seemingly trivial requests. We'll ask new contributers to read this etiquette info for that reason ! \! * A one-time patch from someone passing through may need nothing more than a polite thank you regardless of the content. If a submitter does aim for committership, best to make it plain you're planning to stay around on the project. * Break up unrelated changes. It wouldn't be considered correct for a committer to glom together too many unrelated changes within a single commit, and so we won't commit this kind of patch from submitters. * You need a JIRA for any patch to be attached to, which should accurately describe the change. h2. How to design and implement Big Ideas Every so often someone has a Big Idea that they get excited about and want to go do. They generally mail the list about it to give people the opportunity to comment, and then when nobody says anything they go off and do it. Fast forward six months later they commit/merge/enable/publish the result of their Big Idea, and suddenly everyone understands the full implications, and not everyone is happy. h3. Guidelines To ensure the success of a Big Idea, it is important to: * Communicate it well. * Design it well. So, here are a few guidelines for making sure this doesn't happen, starting with how to write a good proposal for a Big Idea: Guidelines for doing this are described below. * Make sure your proposal is recognizable as a proposal. An easy way to avoid ambiguity is to start a new thread for your proposal and stick "proposal" somewhere in the subject. h3. Communication Guidelines So, here are a few guidelines for making sure this doesn't happen, starting with how to write a good proposal for a Big Idea: * Make sure your proposal is recognizable as a proposal. An easy way to avoid ambiguity is to start a new thread for your proposal and stick "proposal" somewhere in the subject. * Understand who and what your proposal eaffects, and make this clear. If you think X's implementation of Y doesn't deserve to live and you're going to rewrite the whole thing from scratch then make this very clear so X can object sooner rather than later. * Make sure you call out loudly that you intend to kill feature A, even if you think no-one on earth should care. * Even if you're going to write an Atari emulator, and you're 100% sure that it won't overlap with anything in the rest of the project, make sure you understand how and why it relates to the rest of the project in general, and make that clear. * Be concrete. Often a proposal of the form "hey, I did a little of this, here is a proof-of-concept, I'd like to do it for real now" is far more effective than a proposal of the form "hey, I have this vague idea about this, I'm going to vaguely suggest it would be good if someone did it". * Talk about the long term implications of your proposal. If it's code then someone needs to maintain it, and committers will expect this to be you. Make clear your intentions. * Never assume silence implies complicity, more likely it means people didn't understand the implications of your proposal, or didn't have time to figure out why they didn't like it. Ask again \! * The bigger your idea is, the more time and effort you should spend on the proposal, and ensuring that you get positive responses and deal with the comments and feedback provided in your actual implementation. * Even if you're going to write an Atari emulator, and you're 100% sure that it won't overlap with anything in the rest of the project, make sure you understand how and why it relates to the rest of the project in general, and make that clear. h4. Talk early, talk often * Be concrete. Often a proposal of the form "hey, I did a little of this, here is a proof-of-concept, I'd like to do it for real now" is far more effective than a proposal of the form "hey, I have this vague idea about this, I'm going to vaguely suggest it would be good if someone did it". No matter how incredibly excellent your proposal is, there is going to need to be some discussion before the result of your Big Idea is blessed. Here are some things you can do to help that discussion go smoothly: * Make frequent progress reports. Every hour/day/week/month you spend working without telling people what you're doing is an hour/day/week/month of your time that you risk wasting. * Define milestones and make them visible to the rest of the project. Just like a concrete proof-of-concept can help a proposal, it helps to give people a concrete look at what you're doing while it's in progress. This can go a long way towards avoiding surprises. * Talk about the long term implications of your proposal. If it's code then someone needs to maintain it, and committers will expect this to be you. Make clear your intentions. h4. Notify others when you're nearly ready to commit * Never assume silence implies complicity, more likely it means people didn't understand the implications of your proposal, or didn't have time to figure out why they didn't like it. Ask again ! When the time does come to commit/merge/enable/publish your Big Idea, it really shouldn't be a surprise to anyone if you've followed the steps up until now, but make sure you let people know in advance by making note in your final few progress reports of when you expect to be finished, and sending a note to the dev list a day or so before you flip the big switch. * The bigger your idea is, the more time and effort you should spend on the proposal, and ensuring that you get positive responses and deal with the comments and feedback provided in your actual implementation. h3. Design guidelines h3. Talk early, talk often No matter how incredibly excellent your proposal is, there is going to need to be some discussion before the result of your Big Idea is blessed. Here are some things you can do to help that discussion go smoothly: * Make frequent progress reports. Every hour/day/week/month you spend working without telling people what you're doing is an hour/day/week/month of your time that you risk wasting. * Define milestones and make them visible to the rest of the project. Just like a concrete proof-of-concept can help a proposal, it helps to give people a concrete look at what you're doing while it's in progress. This can go a long way towards avoiding surprises. h3. And finally ..... When the time does come to commit/merge/enable/publish your Big Idea, it really shouldn't be a surprise to anyone if you've followed the steps up until now, but make sure you let people know in advance by making note in your final few progress reports of when you expect to be finished, and sending a note to the dev list a day or so before you flip the big switch. A common cause of poor software is that important aspects of the design were not considered early on. Use the checklist below to help you avoid this. * *Impact on public interfaces*, e.g. ** Interoperability with implementations in other languages ** Backwards compatibility ** Documentation (docbook, HTML, etc) * *Performance* * *Security* * *Favour incremental change* \- consider if the change can be split into several smaller ones. This can reduce risk and accelerate "time to market" * *Automated testing* approach: ** For testing the new code, ** and for regression-testing existing functionality that may be affected. * *Operational implications*, e.g. ** Logging ** Monitoring ** Management * *Threading* model * *Memory* management * *Platform-specific considerations*, particularly when considering C+\+ code or language bindings * Implications of executing the code in non-trivial set-ups, especially: ** High availability ** During failover Full Content Purpose This page describes how we do things and why. It includes guidelines on communication, collaboration and design. This guide was originally written by Rafael Schloming. Tell others what you're working on The Qpid project consists of a number of major components spread across almost as many different languages. Thus it is rare for qpid committers to be experts in every single area of the project. As such it is expected that qpid committers make some effort to reach out to their teammates before directly modifying components that are outside their chosen areas. You should use the dev list to reach out to Qpid developers and comment on any JIRAs you're progressing. How to submit and apply patches As a committer it can be difficult to decide whether/how to provide feedback when someone submits a patch. Often it is tempting to just fix up the patch and avoid the slower and sometimes awkward process of telling someone that they got some part of it wrong. However, it is necessary to ensure that those who submit patches get to learn what they need to know in order to become a valued qpid committer. In that spirit, here are a few guidelines for contributing patch submissions and how we handle them: Submitters should produce the final patch(s) as applied to the tree. Producing a patch that needs little or no rework is a key skill for a qpid committer. Maintainers may make requests for 'trivial' updates to the patch. Such requests are vital to ensuring that contributers get familiar with subtle yet important aspects of the code, stylistic conventions, etc. Make sure the submitter is familiar with project etiquette so they understand why we make seemingly trivial requests. We'll ask new contributers to read this etiquette info for that reason ! A one-time patch from someone passing through may need nothing more than a polite thank you regardless of the content. If a submitter does aim for committership, best to make it plain you're planning to stay around on the project. Break up unrelated changes. It wouldn't be considered correct for a committer to glom together too many unrelated changes within a single commit, and so we won't commit this kind of patch from submitters. You need a JIRA for any patch to be attached to, which should accurately describe the change. How to design and implement Big Ideas Every so often someone has a Big Idea that they get excited about and want to go do. They generally mail the list about it to give people the opportunity to comment, and then when nobody says anything they go off and do it. Fast forward six months later they commit/merge/enable/publish the result of their Big Idea, and suddenly everyone understands the full implications, and not everyone is happy. To ensure the success of a Big Idea, it is important to: Communicate it well. Design it well. Guidelines for doing this are described below. Communication Guidelines So, here are a few guidelines for making sure this doesn't happen, starting with how to write a good proposal for a Big Idea: Make sure your proposal is recognizable as a proposal. An easy way to avoid ambiguity is to start a new thread for your proposal and stick "proposal" somewhere in the subject. Understand who and what your proposal affects, and make this clear. If you think X's implementation of Y doesn't deserve to live and you're going to rewrite the whole thing from scratch then make this very clear so X can object sooner rather than later. Make sure you call out loudly that you intend to kill feature A, even if you think no-one on earth should care. Even if you're going to write an Atari emulator, and you're 100% sure that it won't overlap with anything in the rest of the project, make sure you understand how and why it relates to the rest of the project in general, and make that clear. Be concrete. Often a proposal of the form "hey, I did a little of this, here is a proof-of-concept, I'd like to do it for real now" is far more effective than a proposal of the form "hey, I have this vague idea about this, I'm going to vaguely suggest it would be good if someone did it". Talk about the long term implications of your proposal. If it's code then someone needs to maintain it, and committers will expect this to be you. Make clear your intentions. Never assume silence implies complicity, more likely it means people didn't understand the implications of your proposal, or didn't have time to figure out why they didn't like it. Ask again ! The bigger your idea is, the more time and effort you should spend on the proposal, and ensuring that you get positive responses and deal with the comments and feedback provided in your actual implementation. Talk early, talk often No matter how incredibly excellent your proposal is, there is going to need to be some discussion before the result of your Big Idea is blessed. Here are some things you can do to help that discussion go smoothly: Make frequent progress reports. Every hour/day/week/month you spend working without telling people what you're doing is an hour/day/week/month of your time that you risk wasting. Define milestones and make them visible to the rest of the project. Just like a concrete proof-of-concept can help a proposal, it helps to give people a concrete look at what you're doing while it's in progress. This can go a long way towards avoiding surprises. Notify others when you're nearly ready to commit When the time does come to commit/merge/enable/publish your Big Idea, it really shouldn't be a surprise to anyone if you've followed the steps up until now, but make sure you let people know in advance by making note in your final few progress reports of when you expect to be finished, and sending a note to the dev list a day or so before you flip the big switch. Design guidelines A common cause of poor software is that important aspects of the design were not considered early on. Use the checklist below to help you avoid this. Impact on public interfaces, e.g. Interoperability with implementations in other languages Backwards compatibility Documentation (docbook, HTML, etc) Performance Security Favour incremental change - consider if the change can be split into several smaller ones. This can reduce risk and accelerate "time to market" Automated testing approach: For testing the new code, and for regression-testing existing functionality that may be affected. Operational implications, e.g. Logging Monitoring Management Threading model Memory management Platform-specific considerations, particularly when considering C++ code or language bindings Implications of executing the code in non-trivial set-ups, especially: High availability During failover Change Notification Preferences View Online | View Changes | Add Comment --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org