Process Overview

Issue Reporting Writing Code Code Review

THINGS ARE A BIT MURKY! Several points to get across here: 1. The project doesn't have much public involvement, so we can't be sure about everything because there's not much previous data to go on. 2. Process details may change as we find flaws 3. We don't have practical experience with distributed development with git. We haven't necessarily standardized our methods for contributing code with git. What we propose here may change.

JIRA Issue reports should be made at https://issues.asterisk.org/jira in the Asterisk SCF project. Try as much as possible to include involved components in your issue report. JIRA is used for both bugs and for new features, but new features MUST have a patch present. Code contributions require that you sign a contributor license agreement. JIRA usage for Asterisk SCF is very similar to the Asterisk project, except we use the ASTERISK-SCF project. Unlike with Asterisk, Asterisk SCF is very component-driven, so it's important to always indicate which components are involved in the issue being reported. We say that you have to have a patch, but it may be that we end up using a tool like github and using pull requests.

Coding Guidelines - Common Items in namespaces should not be indented 4 space indentation Interface, class, and structure names should be in UpperCamelCase Function, operation, and member variables are in lowerCamelCase These are coding guidelines that are common for both slice and C++ documents. It's important to stress the differences with regards to Asterisk coding guidelines. In Asterisk, they use tabs for indentation instead of four spaces. In Asterisk, they use underscores as a separator between words in type/function names. Also, be prepared for “boos” and hisses from the crowd when certain guidelines are mentioned. It's just the way it is.

Coding Guidelines - Common (Continued) Comments for methods, interfaces, etc. should use Doxygen's Javadoc form Please write comments in English Comments should be used at the end of namespaces to indicate which namespace is being closed More Asterisk differences: Doxygen is used in Asterisk, but not javadoc style. There are no namespaces in Asterisk, of course, since C does not have namespaces.

Coding Guidelines - Slice Empty definitions may have their opening and closing braces on the same line as the definition Slice files will end with “If.ice”. This makes it easy to see that generated files are from slice. Use #pragma once to protect from having the file included multiple times Use C-style comments (/*...*/) since MCPP has issues with C++ style comments. Note to people that some of these guidelines are not hard and fast rules. For instance, the first guideline is not necessarily followed at all times, but it is allowed. To expand on the last point, this can actually cause translation problems when C++ style comments are used at the end of a line. This was commonly seen when commenting the end of a namespace in Slice.

Coding Guidelines - C++ End all files with a newline. g++ is picky about this for some stupid reason. With pointers and references, place the & or * next to the type rather than the variable name. Write modifiers like const and static to the left of the type Single argument class and struct constructors should be marked explicit The second bullet point flies in the face of Asterisk conventions. That last bullet point may not be strictly followed currently in Asterisk SCF.

Coding Guidelines - C++ Headers Use #pragma once to protect against having the header being included multiple times. Use forward declarations if the entire type definition is not needed. Be sure to #include all other header files needed. Source files that include your header should not need to include files they are not directly using. For the second bullet point, this happens most often when a pointer or reference to a type is required, but nothing more is. Let's explain that third point a bit more. If you have a header file that makes use of something from another header, then declare that second header there in your header. Otherwise, every source file that includes your header will be forced to include the secondary header. That is no good.

Coding Guidelines - C++ Headers Use a lowercase 'm' prefix for member variables Avoid “using namespace ...” in headers. Note that this m-prefix thing only applies to C++ members and not slice members. “using namespace x” in headers can pollute the namespace and we don't want that.

Coding Guidelines - C++ Source Organize #include headers based on level First come System level headers Next come library headers (Boost, PJLIB, etc.) Finally come the local headers Flatten namespaces in the source, not in header files Assign variables using constructor syntax, rather than assignment. Nothing much to add here...

Coding Guidelines - C++ Source Write function calls with no whitespace between the function name and opening parenthesis. Statements like for, while, if, switch, etc, should have a space before the opening parenthesis. Compound statements must always be enclosed in braces. This holds true even if the block contains a single statement

https://wiki.asterisk.org/wiki/display/TOP/Style+Guide This link has all the style guidelines and picture examples.

Tests If it is at all possible, write automated unit tests for your new code. If you are modifying existing code, add new test cases or modify existing ones to exercise the new code.

Boost unit tests We use Boost unit test functionality heavily in Asterisk SCF, so becoming familiar with it is useful. We have some CMake functions written to easily allow building Boost unit tests and to incorporate them into automated tests.

Code Reviews Atlassian Crucible https://code.asterisk.org/code/cru

Crucible Uses the same single sign-on as the wiki. If you have a wiki account, then you automatically have a crucible account. You may need to send a message to the developer mailing list to get your role changed so you will be allowed to author reviews. It is recommended that you first open an issue in JIRA for your code contribution before opening a code review.

Crucible - Code Contributor Contributing code reviews requires signing the same contributor license agreement as for contributing code on the issue tracker. Click the “Add Review” button to create a new review. Add whatever content you wish to the review. This may be any revision or any code in any repository. Add reviewers to the review. Look at the review blockers report to avoid adding someone with a large review backlog

Crucible - Code Contributor (Continued) Wait for the reviewers to complete their reviews. Please be patient here. Reviewers often are very busy and may not be able to get to your review right away. If necessary, make revisions and update the review. Repeat until all reviewers have completed their review with no negative feedback.

Crucible - Reviewer If you are added as a reviewer, please be sure to review the code in a timely manner. If you are added as a reviewer but do not feel comfortable reviewing the code in question, don't feel shamed removing yourself from the review. If possible, recommend alternate people to review in your place.