Wed Jan 8 2020 09:49:48

Asterisk developer's documentation


mantisworkflow.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2009, Digium, Inc.
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16 
17 /*!
18  * \file
19  */
20 
21 /*!
22  * \page MantisWorkflow Workflow Guidelines for Asterisk Open Source Issue Tracker
23  *
24  * \AsteriskTrunkWarning
25  *
26  * <hr/>
27  * \section WorkflowDescription Description of the Issue Tracker Workflow
28  *
29  * (This document is most beneficial for Asterisk bug marshals, however it is good
30  * reading for anyone who may be filing issues or wondering how the Asterisk Open
31  * Source project moves issues through from filing to completion.)
32  *
33  * The workflow in the issue tracker should be handled in the following way:
34  *
35  * -# A bug is reported and is automatically placed in the 'New' status.
36  * -# The Bug Marshall team should go through bugs in the 'New' status to determine
37  * whether the report is valid (not a duplicate, hasn't already been fixed, not
38  * a Digium tech support issue, etc.). Invalid reports should be set to
39  * 'Closed' with the appropriate resolution set. Categories and descriptions
40  * should be corrected at this point.[Note1]\n
41  * Issues should also have enough information for a developer to either
42  * reproduce the issue or determine where an issue exists (or both). If this is
43  * not the case then the issue should be moved to 'Feedback' prior to moving
44  * forward in the workflow.
45  * -# The next step is to determine whether the report is about a bug or a
46  * submission of a new feature:
47  * -# BUG: A bug should be moved into the status 'Acknowledged' if enough
48  * information has been provided by the reporter to either reproduce the
49  * issue or clearly see where an issue may lie. The bug may also be
50  * assigned to a developer for the creation of the initial patch, or
51  * review of the issue.\n
52  * Once a patch has been created for the issue and attached, the issue can
53  * then be moved to the 'Confirmed' status. At this point, initial code
54  * review and discussion about the patch will take place. Once an adequate
55  * amount of support for the implementation of the patch is acquired, then
56  * the bug can be moved to the 'Ready for Testing' status for wider
57  * testing by the community. After the testing phase is complete and it
58  * appears the issue is resolved, the patch can be committed by a
59  * developer and closed.
60  * -# FEATURE: As new features should be filed with a patch, it can be
61  * immediately moved to the 'confirmed' status, making it ready for basic
62  * formatting and code review. From there any changes to style or feel of
63  * the patch based on feedback from the community can be discussed, and
64  * changes to the patch made. It can then be moved forward to the 'Ready
65  * for Testing' status. Once the feature has been merged, or a decision
66  * has been made that it will not be merged, the issue should be taken to
67  * 'Closed' with the appropriate resolution.[Note2]
68  * -# If at any point in the workflow, an issue requires feedback from the original
69  * poster of the issue, the status should be changed to 'Feedback'. Once the
70  * required information has been provided, it should be placed back in the
71  * appropriate point of the workflow.
72  * -# If at any point in the workflow, a developer or bug marshal would like to
73  * take responsibility for doing the work that is necessary to progress an
74  * issue, the status can be changed to 'Assigned'. At that point the developer
75  * assigned to the issue will be responsible for moving the issue to completion.
76  *
77  * \section WorkflowSummary Workflow Summary
78  *
79  * The following is a list of valid statuses and what they mean to the work flow.
80  *
81  * \subsection New New
82  * This issue is awaiting review by bug marshals. Categorization and summaries
83  * should be fixed as appropriate.
84  *
85  * \subsection Feedback
86  * This issue requires feedback from the poster of the issue before any
87  * additional progress in the workflow can be made. This may include providing
88  * additional debugging information, or a backtrace with DONT_OPTIMIZE enabled,
89  * for example. (See https://wiki.asterisk.org/wiki/display/AST/Debugging)
90  *
91  * \subsection Acknowledged
92  * This is a submitted bug which has no patch associated with it, but appears
93  * to be a valid bug based on the description and provided debugging
94  * information.
95  *
96  * \subsection Confirmed
97  * The patch associated with this issue requires initial formatting and code
98  * review, and may have some initial testing done. It is waiting for a
99  * developer to confirm the patch will no longer need large changes made to it,
100  * and is ready for wider testing from the community. This stage is used for
101  * discussing the feel and style of a patch, in addition to the coding style
102  * utilized.
103  *
104  * \subsection Ready For Testing
105  * This is an issue which has a patch that is waiting for testing feedback from
106  * the community after it has been deemed to no longer need larger changes.
107  *
108  * \subsection Assigned
109  * A developer or bug marshal has taken responsibility for taking the necessary
110  * steps to move forward in the workflow. Once the issue is ready to be
111  * reviewed and feedback provided, it should be placed back into the
112  * appropriate place of the workflow.
113  *
114  * \subsection Resolved
115  * A resolution for this issue has been reached. This issue should immediately
116  * be Closed.
117  *
118  * \subsection Closed
119  * No further action is necessary for this issue.
120  *
121  * \section SeverityLevels Severity Levels
122  *
123  * Severity levels generally represent the number of users who are potentially
124  * affected by the reported issue.
125  *
126  * \subsection Feature Feature
127  * This issue is a new feature and will only be committed to Asterisk trunk.
128  * Asterisk trunk is where future branches will be created and thus this
129  * feature will only be found in future branches of Asterisk and not merged
130  * into existing branches. (See Release Branch Commit Policy below.)
131  *
132  * \subsection Trivial Trivial
133  * A trivial issue is something that either affects an insignificant number of
134  * Asterisk users, or is a minimally invasive change that does not affect
135  * functionality.
136  *
137  * \subsection Text Text
138  * A text issue is typically something like a spelling fix, a clarifying of a
139  * debugging or verbose message, or changes to documentation.
140  *
141  * \subsection Tweak Tweak
142  * A tweak to the code the has the potential to either make code clearer to
143  * read, or a change that could speed up processing in certain circumstances.
144  * These changes are typically only a couple of lines.
145  *
146  * \subsection Minor Minor
147  * An issue that does not affect a large number of Asterisk users, but not an
148  * insignificant number. The number of lines of code and development effort to
149  * resolve this issue could be non-trivial.
150  *
151  * \subsection Major Major
152  * As issue that affects the majority of Asterisk users. The number of lines of
153  * code and development effort required to resolve this issue could be
154  * non-trivial.
155  *
156  * \subsection Crash Crash
157  * An issue marked as a Crash is something that would cause Asterisk to be
158  * unusable for a majority of Asterisk users and is an issue that causes a
159  * deadlock or crash of the Asterisk process.
160  *
161  * \subsection Block Block
162  * A blocking issue is an issue that must be resolved before the next release
163  * of Asterisk as would affect a significant number of Asterisk users, or could
164  * be a highly visible regression. A severity of block should only be set by
165  * Asterisk bug marshals at their discretion.
166  *
167  * *** USERS SHOULD NOT FILE ISSUES WITH A SEVERITY OF BLOCK ***
168  *
169  * \section PriorityLevels Priority Levels
170  *
171  * Currently, the following priority levels are listed on the issue tracker:
172  * - None
173  * - Low
174  * - Normal
175  * - High
176  * - Urgent
177  * - Immediate
178  *
179  * However, at this time they are not utilized and all new issue should have a priority of 'Normal'.
180  *
181  * \section Notes Notes
182  *
183  * -# Using the "Need Triage" filter is useful for finding these issues quickly.
184  * -# The issue tracker now has the ability to monitor the commits list, and if
185  * the commit message contains something like, "(Closes issue #9999)", the bug
186  * will be automatically closed.\n
187  * See http://www.asterisk.org/doxygen/trunk/CommitMessages.html for more
188  * information on commit messages.
189  *
190  * \section ReleaseBranchCommitPolicy Release Branch Commit Policy
191  *
192  * The code in the release branches should be changed as little as possible. The
193  * only time the release branches will be changed is to fix a bug. New features
194  * will never be included in the release branch unless a special exception is made
195  * by the release branch maintainers.
196  *
197  * Sometimes it is difficult to determine whether a patch is considered to fix a
198  * bug or if it is a new feature. Patches that are considered code cleanup, or to
199  * improve performance, are NOT to be included in the release branches. Performance
200  * issues will only be considered for the release branch if they are considered
201  * significant, and should be approved by the maintainers.
202  *
203  * If there is ever a question about what should be included in the release branch,
204  * the maintainers should be allowed to make the decision.
205  */