Document Maintainers and Testing. - Extend The Developer Manual to document Maintainer and Testing Processes. - Update main page with references and overview of these new pages. --- main.txt | 15 ++++ maintainers.txt | 139 ++++++++++++++++++++++++++++++++++++++++++++ testing.txt | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 328 insertions(+), 2 deletions(-)
Document Maintainers and Testing. - Extend The Developer Manual to document Maintainer and Testing Processes. - Update main page with references and overview of these new pages. --- main.txt | 15 ++++ maintainers.txt | 139 ++++++++++++++++++++++++++++++++++++++++++++ testing.txt | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 328 insertions(+), 2 deletions(-) ====== only in patch2: unchanged: --- doc/manual/main.txt (revision 2495) +++ doc/manual/main.txt (working copy) @@ -8,7 +8,6 @@ Developers that want to contribute to OpenOCD should read the following sections before starting work: - - The List of @subpage thelist enumerates opportunities for improving or extending the OpenOCD platform. If your ideas are on The List, you might check the mailing list archives to find the status of your feature (or bug). @@ -18,8 +17,20 @@ follow when submitting patches to the project. - The @subpage bugs page contains the content of the BUGS file, which provides instructions for submitting bug reports to the maintainers. -- The @subpage releases page describes the project's release process. +After these processes have become second nature, you may want to +become involved with the ongoing strategic goals of project, including +maintainence, testing, and releases. The following sections will allow +you to become familiarized with the project's strategic processes: +- The @subpage maintainers page describes OpenOCD's maintainers, from + their origin and function to roles, responsibilities, and authority. +- The @subpage testing page describes the project's testing processes, + including the purpose of test suites, how and when to test, and who + will be responsibile for making decisions about testing. +- The @subpage releases page describes the steps required to produce + periodic releases of the repository in a form suitable for users, + after describing why, how, and when these should be made. + @ref primer provide introductory materials for new developers on various specific topics. only in patch2: unchanged: --- doc/manual/maintainers.txt (revision 0) +++ doc/manual/maintainers.txt (revision 0) @@ -0,0 +1,139 @@ +/** @page maintainers Maintainer Guildelines + +This page provides guidelines for OpenOCD maintainers to follow. + +...@section maintainerwhy Why Does OpenOCD Have Maintainers? + +When the project grew beyond the ability for Dominic Rath to manage on +his own, the OpenOCD project has been managed by a group of Maintainers. +These individuals are entrusted as the gatekeepers for the project, +ensuring that development activities remain coordinated as the project +scales with ongoing growth. + +...@section maintainerwho Who Are The OpenOCD Maintainers? + +The names of current OpenOCD maintainers can be found on the BerliOS +Project Site: @par +http://developer.berlios.de/project/memberlist.php?group_id=4148 + +Maintainers may commit to the Subversion repository. This privilege +comes with responsibility that non-maintaining contributors do not have. + +In addition the willingness and ability to contribute their own work to +the project, maintainers should help others with their work, fixing bugs +and providing answers in whatever capacity available. In this way, +there are as many roles for maintainers as there are contributors, but +maintainers have the responsibility of making the final decisions when +consensus cannot be reached by the contributing community. + +Maintainers must be willing to work within the limits imposed by the +community's processes and guidelines, as these standards were designed +to protect the strategic integrity of the project. + +...@section maintainerwhohow How Do I Become A Maintainer? + +The process to becoming a maintainer requires starting by demonstrating +the ability to be a contributor. Once a solid track record has been +established through the mailing list, you may be invited to participate +in a maintaining capacity. + +...@subsection maintainerwhoexec Who Is In Charge? + +Active contributors provide guidance for the maintainers, who have the +final power to decide matters in their respective areas of authority. +Each maintainer may fill one or more roles, which grant them power +commiserate with their associated responsibilities. + +The Project Managers provide oversight and guidance over the execution +of the project processes. In this role, these individuals should be +empowered to make executive decisions in order to cut through dissent in +the community. An excellent example would be ending flame wars; +their decisions should be viewed as final and uncontestable. + +Other Managers hold equivalent (or higher) rank than these individuals. +The @ref releasewho oversee and execute the @ref releases. The @ref +testingwhotm oversee or execute the testing processes. Other managers +may be given oversight over particular areas of the code. + +Should the project managers ever fail to reach consensus, our world +could come to an end -- or the community could be asked to vote. +Mob rule should be the last resort, so such events should be very rare. + +...@subsection maintainerauthority Who Has Authority? + +In many respects, some authority exists (by copyright) in the original +author(s) of the code in question, but the ultimate authority returns to +the active contributing community. OpenOCD's managers must be held +accountable for their mistakes by the community. Individuals that +repeated and grossly fail to meet the standards of their roles should +lose the privilege to execute those responsibilities for the community. + +The maintainers should be serving the needs of the user community, not +only their own personal projects. Those who contribute in this way +should be given continued accolade and privilege. Those who fail to +serve the community should find themselves berated by the masses for +failing to live up to their responsiblities, and their privileges may +eventually be revoked. + +...@section maintainerhow Maintainer Processes + +This section provides guidelines for maintainers to follow. + +...@subsection maintainerlist Project Mailing Lists + +The openocd-development@lists.berlios.de mailing list provides the +primary means for communicating with all members of the community. +All maintainers are expected to follow the traffic on this list, so +you should participate regularly in discussions in your expert domain. + +In addition, the openocd-...@lists.berlios.de mailing list provides +Subersion commit messages, which relays all changes made to the +repository to its subscribers. This allows nearly real-time +notification of changes that have been made. Maintainers are encouraged +to follow this list and review all patches that are committed, to +prevent rogue agents from embedding malicious code (or dedicated +developers from bringing benevolent bugs). + +...@subsection maintainercommit Patch Commit Guidelines + +Maintainers have the privilege of commiting patches to the project +repository. This section details the guidelines for accepting and +committing patches: + +- Review the submitted patch: + - Ensure the new changes conform to all style guidelines. + - Ensure the patch contains a single or small set of changes. + - For core changes, determining patch correctness must be trivial. + - Contributors must split larger patches into series. + - Ensure the commit message describes all changes in the repository. +- When commiting patches produced by others, the first line should + provide the name and e-mail of the individual(s) that developed them, + following by a blank line before the actual commit message: +...@verbatim +John Doe <john....@example.com>: + +Commit message starts here. +...@endverbatim + +During normal development, maintainers may commit their own pathces +directly to the repository. Maintainers that commit their own patches +-- without meeting the standards that apply to all contributors' patches +-- may find their privileges revoked after repeatedly failing to address +the shortcomings of the work that they have commited in this way. + +To remain in good standing, maintainers should minimize transgressions +in their own patches and ensure the rest of the community follows best +practices. If in doubt about their compliance, maintainers should post +their patches to the mailing list for 24 hours, as this ensures that +another maintainer will have had the opportunity review it and offer +advice to avoid possible recrimination. Maintainers are expected to +commit their own patches after this review period. + +During the release process, maintainers @b must post their patches for +review on the mailing list. Direct commits should not be allowed, +excepting in special circumstances that remain to be documented. + + */ +/** @file +This file contains the @ref maintainers page. + */ only in patch2: unchanged: --- doc/manual/testing.txt (revision 0) +++ doc/manual/testing.txt (revision 0) @@ -0,0 +1,176 @@ +/** @page testing Testing Processes + +The following sections answer several important questions about +the OpenOCD testing process. + +- @ref testingwhy : Gives motivation for testing regularly. +- @ref testingwho : Explains who can perform testing. +- @ref testinghow : Outlines testing procedures. +- @ref testingwhen : Provides guidelines for integrating testing into + other development processes. + +...@section testingwhy Why Perform Testing? + +Testing can detect errors. Without a testing process, users will detect +your errors and report them. This will be depressing for both you and +your users, but comparative anaylsis of these experiences will lead you +to realize that @a preventing bugs leaves you with much happier users. + +Thus, testing can help prevent bug reports by detecting errors before +the code has been released to the general user population. + +...@subsection testingwhyauto Why Develop Test Automation? + +Testing requires running a multitude of tests against the code base, +such that the test suite provides complete @a coverage of the source +code. Scripts and test programs tend to be the only means of achieving +repeatabible test coverage. + +...@subsection testingwhymanual Can We Automate Everything? + +Unfortunately, many testing procedures for OpenOCD require hands-on +interaction with the hardware under test. While scripts can be +developed to automate the software, physical connections may need to be +reconfigured in between successive testing steps. + +As a result of these limitations, the testing procedures will always +require more effort than some software packages, even if the developers +can automate the vast majority of the testing processes. + +...@subsection testingwhybeta What About "Beta Testing"? + +Some organizations release "eternal beta" software; others release a +product as "1.0" that seems to have skipped the "beta" stage, so their +code stinks until their 1.1 release. If you work in the software +industry, you will experience both of these extremes at some point. + +With "release early, release often," open source and free software tends +to fall into the later camp. However, most developers have the good +sense and courtesy to start their versions at 0.0.0 -- not 1.0.0. +Conventionally, anything less than 1.0 is "de facto beta". This +definition may snare a number of standard GNU/Linux libraries, but their +developers may agree with the definition in light of the following. + +By not released 1.0, the developers indicate that they know their code +is incomplete or still subject to radical change. Alternatively, they +are unwilling to increment the version and take responsibility for +stable releases. Any way you look at it, those are not attributes of +quality production code, so those projects need to be treated with some +degree of caution. Users must recognize that things could always change +in the next release. + +Until OpenOCD reaches its 1.0, all releases should be considered "beta" +to some extent; however, this should not discourage anyone with +reasonable expectations about open source. If anything, this position +should make it clear that some assembly may be required if you choose to +use OpenOCD; anyone that @a does want an out-of-the-box solution should +be aware of these facts in advance. + +...@subsection testingwhybeta What About "-rc" Releases? + +When OpenOCD's active user base has grown sufficiently, we can introduce +-rc series to get an intermediate testing base between developers and +the entire user population. In the above "beta" context, this may be +postponed until 1.0 or beyond, whereupon "beta" is no longer implicit +from our 0.y.z version numbering. + +Presently, all OpenOCD users are beta testers, because the code is going +to go through radical changes before we reach 1.0, and we do not have +any intention (as a community) to provide support for the past releases. + +...@section testingwho Who Performs Testing? + +Everyone that uses OpenOCD should participate in the testing processes. + +The following subsections describe the varying resposibilities that are +delegated to different types of contributors. + +...@subsection testingwhotm Testing Manager + +The OpenOCD community empowers one or more <i>Testing Manager</i> +(or TM) to provide oversight of the testing processes for areas of +functionality. OpenOCD supports too many kinds of hardware for any +individual to test tham all alone, so the community must work together +to produce, report, and respond to test results. + +A Testing Manager is responsible for ensuring that their assigned area +of the OpenOCD tree receives adequate testing coverage, whether by +automated or interactive processes. When showing due cause, they have +the authority to reject patches, hold release process, and otherwise +work to ensure the project meets all documented standards of quality, +function, and style. + +...@subsection testingwhodev Community Testing + +Presently, There are two kinds of community testing: developer and user. +The distinction is rather aribtrary, as most developers are also users. +However, developers can provide and use advanced automation, whereas +most users should be expected to run that automation and report the +results back to the developers. + +...@subsubsection testingwhodev Developer Testing + +Developers should be using and testing the SVN trunk HEAD, to ensure +that each successive release has been exposed to many different +development and testing environments. Once developers have tested a +certain tree, it can be released for users. + +...@subsection testingwhouser User Testing + +Users should be testing the source archive releases, if only by virtue +of using our package and finding bugs during daily use. + +Users should never be asked to test the SVN. Instead, developers can +produce a development source archive release for the user to test, or +the user can wait for fixes to appear in the next official release. + +Once OpenOCD has a large community of active users, -rc archives can be +produced and distributed for testing by a subset of users. Until then, +the community will be served better by producing regular releases on a +periodic basis, working to raise the bar of performance and stability +with each successive release. + +...@section testinghow What Are The Testing Processes? + +This section describes different testing processes, providing steps +for using the automated and interactive test suites. + +...@subsection testinghowauto How Do I Run Automated Tests? + +The autotools build system can run tests automatically as part of the +<code>make</code> process target. The <code>check</code> and +<code>distcheck</code> targets both will run the scripts and programs +specified by the automake TEST variables. + +...@subsection testinghowuser How Do I Run Manual Tests? + +Standards need to be developed for manual testing, which include testing +harnesses that guide users through the processes step-by-step. When +these are developed, they should be documented here. + +...@section testingwhen When Should Testing Be Done? + +Testing should be performed continuously. This section provides details +about the different times when testing can be used to prevent +regressions and improve quality. + +...@subsection testingwhencommits Commit Testing + +An automated build process that triggers on comments could ensure that +new patches compile on all platforms without warnings. + +...@subsection testingwhenrelease Release Testing + +At the end of a release cylcle, the @ref releases demand greater +developer restraint and testing scrutiny. The focus should be directed +at fixing bugs in the build, packaging, run-time, and documentation +aspects of the project. + +- All patches must be reviewed by the community for 12 hours. +- New features should be delayed until after the release. + + + */ +/** @file +This file contains the @ref testing page. +
_______________________________________________ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
