erkin yucel / mbed-os

mbed os with nrf51 internal bandgap enabled to read battery level

Dependents:   BLE_file_test BLE_Blink ExternalEncoder

docs/COMMITTERS.md@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
elessair 0:f269e3021894 1 # Committing changes to mbedmicro/mbed
elessair 0:f269e3021894 2
elessair 0:f269e3021894 3 * Our current branching model is very simple. We are using ```master``` branch to merge all pull requests.
elessair 0:f269e3021894 4 * Based on stable ```SHA``` version of ```master``` branch we decide to release and at the same time ```tag``` our build release.
elessair 0:f269e3021894 5 * Our current release versioning follows simple integer version: ```94```, ```95```, ```96``` etc.
elessair 0:f269e3021894 6
elessair 0:f269e3021894 7 # Committer Guide
elessair 0:f269e3021894 8
elessair 0:f269e3021894 9 ## How to decide what release(s) should be patched
elessair 0:f269e3021894 10 This section provides a guide to help a committer decide the specific base branch that a change set should be merged into.
elessair 0:f269e3021894 11
elessair 0:f269e3021894 12 Currently our default branch is ```master``` branch. All pull requests should be created against ```master``` branch.
elessair 0:f269e3021894 13 mbed SDK is released currently on master branch under certain tag name (see [Git tagging basics]( http://git-scm.com/book/en/v2/Git-Basics-Tagging)). You can see mbed SDK tags and switch between them to for example go back to previous mbed SDK release.
elessair 0:f269e3021894 14 ```
elessair 0:f269e3021894 15 $ git tag
elessair 0:f269e3021894 16 ```
elessair 0:f269e3021894 17
elessair 0:f269e3021894 18 Please note: mebd SDK ```master``` branch's ```HEAD``` is our latest code and may not be as stable as you expect. We are putting our best effort to run regression testing (in-house) against pull requests and latest code.
elessair 0:f269e3021894 19 Each commit to ```master``` will trigger [GitHub's Travis Continuous Integration](https://travis-ci.org/mbedmicro/mbed/builds).
elessair 0:f269e3021894 20
elessair 0:f269e3021894 21 ### Pull request
elessair 0:f269e3021894 22 Please send pull requests with changes which are:
elessair 0:f269e3021894 23 * Complete (your code will compile and perform as expected).
elessair 0:f269e3021894 24 * Tested on hardware.
elessair 0:f269e3021894 25 * You can use included mbed SDK test suite to perform testing. See TESTING.md.
elessair 0:f269e3021894 26 * If your change, feature do not have a test case included please add one (or more) to cover new functionality.
elessair 0:f269e3021894 27 * If you can't test your functionality describe why.
elessair 0:f269e3021894 28 * Documented source code:
elessair 0:f269e3021894 29 * New, modified functions have descriptive comments.
elessair 0:f269e3021894 30 * You follow coding rules and styles provided by mbed SDK project.
elessair 0:f269e3021894 31 * Documented pull request description:
elessair 0:f269e3021894 32 * Description of changes is added - explain your change / enhancement.
elessair 0:f269e3021894 33 * References to existing issues, other pull requests or forum discussions are included.
elessair 0:f269e3021894 34 * Test results are added.
elessair 0:f269e3021894 35
elessair 0:f269e3021894 36 After you send us your pull request our Gate Keeper will change the state of pull request to:
elessair 0:f269e3021894 37 • ``` enhancement``` or ```bug``` when pull request creates new improvement or fixed issue.
elessair 0:f269e3021894 38 Than we will set for you labels:
elessair 0:f269e3021894 39 • ```review``` to let you know your pull request is under review and you can expect review related comments from us.
elessair 0:f269e3021894 40 • ```in progress``` when you pull request requires some additional change which will for now block this pull request from merging.
elessair 0:f269e3021894 41 At the end we will remove ```review``` label and merge your change if everything goes well.
elessair 0:f269e3021894 42
elessair 0:f269e3021894 43 ## C++ coding rules & coding guidelines
elessair 0:f269e3021894 44 ### Rules
elessair 0:f269e3021894 45 * The mbed SDK code follows K&R style (Reference: [K&R style](http://en.wikipedia.org/wiki/Indent_style#K.26R_style)) with at least 2 exceptions which can be found in the list below the code snippet:
elessair 0:f269e3021894 46
elessair 0:f269e3021894 47 ```c++
elessair 0:f269e3021894 48 static const PinMap PinMap_ADC[] = {
elessair 0:f269e3021894 49 {PTC2, ADC0_SE4b, 0},
elessair 0:f269e3021894 50 {NC , NC , 0}
elessair 0:f269e3021894 51 };
elessair 0:f269e3021894 52
elessair 0:f269e3021894 53 uint32_t adc_function(analogin_t *obj, uint32_t options)
elessair 0:f269e3021894 54 {
elessair 0:f269e3021894 55 uint32_t instance = obj->adc >> ADC_INSTANCE_SHIFT;
elessair 0:f269e3021894 56 switch (options) {
elessair 0:f269e3021894 57 case 1:
elessair 0:f269e3021894 58 timeout = 6;
elessair 0:f269e3021894 59 break;
elessair 0:f269e3021894 60 default:
elessair 0:f269e3021894 61 timeout = 10;
elessair 0:f269e3021894 62 break;
elessair 0:f269e3021894 63 }
elessair 0:f269e3021894 64
elessair 0:f269e3021894 65 while (!adc_hal_is_conversion_completed(instance, 0)) {
elessair 0:f269e3021894 66 if (timeout == 0) {
elessair 0:f269e3021894 67 break;
elessair 0:f269e3021894 68 } else {
elessair 0:f269e3021894 69 timeout--;
elessair 0:f269e3021894 70 }
elessair 0:f269e3021894 71 }
elessair 0:f269e3021894 72
elessair 0:f269e3021894 73 if (obj->adc == ADC_CHANNEL0) {
elessair 0:f269e3021894 74 adc_measure_channel(instance);
elessair 0:f269e3021894 75 adc_stop_channel(instance);
elessair 0:f269e3021894 76 } else {
elessair 0:f269e3021894 77 error("channel not available");
elessair 0:f269e3021894 78 }
elessair 0:f269e3021894 79
elessair 0:f269e3021894 80 #if DEBUG
elessair 0:f269e3021894 81 for (uint32_t i = 0; i < 10; i++) {
elessair 0:f269e3021894 82 printf("Loop : %d", i);
elessair 0:f269e3021894 83 }
elessair 0:f269e3021894 84 #endif
elessair 0:f269e3021894 85 return adc_hal_get_conversion_value(instance, 0);
elessair 0:f269e3021894 86 }
elessair 0:f269e3021894 87 ```
elessair 0:f269e3021894 88 * Indentation - 4 spaces. Please do not use tabs!
elessair 0:f269e3021894 89 * Braces - K&R, except for functions where the opening brace is on the new line.
elessair 0:f269e3021894 90 * 1 TBS - use braces for statements ```if```, ```else```, ```while```, ```for``` (exception from K&R) Reference: [1TBS](http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS)).
elessair 0:f269e3021894 91 * One line per statement.
elessair 0:f269e3021894 92 * Preprocessor macro starts at the beginning of a new line, the code inside is indented accordingly the code above it.
elessair 0:f269e3021894 93 * Cases within switch are indented (exception from K&R).
elessair 0:f269e3021894 94 * Space after statements if, while, for, switch, same applies to binary and ternary operators.
elessair 0:f269e3021894 95 * Each line has preferably at most 120 characters.
elessair 0:f269e3021894 96 * For pointers, ```*``` is adjacent to a name (analogin_t *obj).
elessair 0:f269e3021894 97 * Don't leave trailing spaces at the end of lines.
elessair 0:f269e3021894 98 * Empty lines should have no trailing spaces.
elessair 0:f269e3021894 99 * Unix line endings are default option for files.
elessair 0:f269e3021894 100 * Use capital letters for macros.
elessair 0:f269e3021894 101 * A file should have an empty line at the end.
elessair 0:f269e3021894 102 and:
elessair 0:f269e3021894 103 * We are not using C++11 yet so do not write code compliant to this standard.
elessair 0:f269e3021894 104 * We are not using libraries like ```BOOST``` so please so not include any ```BOOST``` headers to your code.
elessair 0:f269e3021894 105 * C++ & templates: please take under consideration templates are not fully supported by cross-compilers. You may have difficulties compiling template code few cross-compilers so make sure your template code compilers for more than one compiler.
elessair 0:f269e3021894 106
elessair 0:f269e3021894 107 ### Naming conventions
elessair 0:f269e3021894 108 Classes:
elessair 0:f269e3021894 109 * Begins with a capital letter, and each word in it begins also with a capital letter (```AnalogIn```, ```BusInOut```).
elessair 0:f269e3021894 110 * Methods contain small letters, distinct words separated by underscore.
elessair 0:f269e3021894 111 * Private members starts with an underscore.
elessair 0:f269e3021894 112
elessair 0:f269e3021894 113 User defined types (typedef):
elessair 0:f269e3021894 114 * Structures - suffix ```_t``` - to denote it is user defined type
elessair 0:f269e3021894 115 * Enumeration - the type name and values name - same naming convention as classes (e.g ```MyNewEnum```)
elessair 0:f269e3021894 116
elessair 0:f269e3021894 117 Functions:
elessair 0:f269e3021894 118 * Contain lower case letters (as methods within classes)
elessair 0:f269e3021894 119 * Distinct words separated by underscore (```wait_ms```, ```read_u16```)
elessair 0:f269e3021894 120 * Please make sure that in your module all functions have unique prefix so when your module is compiled with other modules function names (and e.g. extern global variable names) are not in naming conflict.
elessair 0:f269e3021894 121
elessair 0:f269e3021894 122 Example code look&feel:
elessair 0:f269e3021894 123 ```c++
elessair 0:f269e3021894 124 #define ADC_INSTANCE_SHIFT 8
elessair 0:f269e3021894 125
elessair 0:f269e3021894 126 class AnalogIn {
elessair 0:f269e3021894 127 public:
elessair 0:f269e3021894 128 /** Create an AnalogIn, connected to the specified pin
elessair 0:f269e3021894 129 *
elessair 0:f269e3021894 130 * @param pin AnalogIn pin to connect to
elessair 0:f269e3021894 131 * @param name (optional) A string to identify the object
elessair 0:f269e3021894 132 */
elessair 0:f269e3021894 133 AnalogIn(PinName pin) {
elessair 0:f269e3021894 134 analogin_init(&_adc, pin);
elessair 0:f269e3021894 135 }
elessair 0:f269e3021894 136
elessair 0:f269e3021894 137 /** Read the input voltage, represented as a float in the range [0.0, 1.0]
elessair 0:f269e3021894 138 *
elessair 0:f269e3021894 139 * @returns
elessair 0:f269e3021894 140 * A floating-point value representing the current input voltage, measured as a percentage
elessair 0:f269e3021894 141 */
elessair 0:f269e3021894 142 uint32_t read() {
elessair 0:f269e3021894 143 return analogin_read(&_adc, operation);
elessair 0:f269e3021894 144 }
elessair 0:f269e3021894 145
elessair 0:f269e3021894 146 protected:
elessair 0:f269e3021894 147 analogin_t _adc;
elessair 0:f269e3021894 148 };
elessair 0:f269e3021894 149
elessair 0:f269e3021894 150 typedef enum {
elessair 0:f269e3021894 151 ADC0_SE0 = (0 << ADC_INSTANCE_SHIFT) | 0,
elessair 0:f269e3021894 152 } ADCName;
elessair 0:f269e3021894 153
elessair 0:f269e3021894 154 struct analogin_s {
elessair 0:f269e3021894 155 ADCName adc;
elessair 0:f269e3021894 156 };
elessair 0:f269e3021894 157
elessair 0:f269e3021894 158 typedef struct analogin_s analogin_t;
elessair 0:f269e3021894 159 ```
elessair 0:f269e3021894 160 ### Doxygen documentation
elessair 0:f269e3021894 161 All functions / methods should contain a documentation using doxygen javadoc in a header file. More information regarding writing API Documentation, follow [this](https://mbed.org/handbook/API-Documentation) link.
elessair 0:f269e3021894 162
elessair 0:f269e3021894 163 Example of well documentet code:
elessair 0:f269e3021894 164 ```c++
elessair 0:f269e3021894 165 #ifndef ADC_H
elessair 0:f269e3021894 166 #define ADC_H
elessair 0:f269e3021894 167
elessair 0:f269e3021894 168 #ifdef __cplusplus
elessair 0:f269e3021894 169 extern "C" {
elessair 0:f269e3021894 170 #endif
elessair 0:f269e3021894 171
elessair 0:f269e3021894 172 /** ADC Measurement method
elessair 0:f269e3021894 173 *
elessair 0:f269e3021894 174 * @param obj Pointer to the analogin object.
elessair 0:f269e3021894 175 * @param options Options to be enabled by ADC peripheral.
elessair 0:f269e3021894 176 *
elessair 0:f269e3021894 177 * @returns
elessair 0:f269e3021894 178 * Measurement value on defined ADC channel.
elessair 0:f269e3021894 179 */
elessair 0:f269e3021894 180 uint32_t adc_function(analogin_t *obj, uint32_t options)
elessair 0:f269e3021894 181
elessair 0:f269e3021894 182 #ifdef __cplusplus
elessair 0:f269e3021894 183 }
elessair 0:f269e3021894 184 #endif
elessair 0:f269e3021894 185
elessair 0:f269e3021894 186 #endif
elessair 0:f269e3021894 187 ```
elessair 0:f269e3021894 188 ### C/C++ Source code indenter
elessair 0:f269e3021894 189 In Mbed project you can use AStyle (Reference: [Artistic Style](http://astyle.sourceforge.net/)) source code indenter to help you auto format your source code. It will for sure not correct all your coding styles but for sure will eliminate most of them. You can download AStyle from this location.
elessair 0:f269e3021894 190
elessair 0:f269e3021894 191 Official Mbed SDK styles include below AStyle styles (defined by command line switched):
elessair 0:f269e3021894 192 ```
elessair 0:f269e3021894 193 --style=kr --indent=spaces=4 --indent-switches
elessair 0:f269e3021894 194 ```
elessair 0:f269e3021894 195 To format your file you can execute below command. Just replace ```$(FULL_CURRENT_PATH)``` with path to your source file.
elessair 0:f269e3021894 196 ```
elessair 0:f269e3021894 197 $ astyle.exe --style=kr --indent=spaces=4 --indent-switches $(FULL_CURRENT_PATH)
elessair 0:f269e3021894 198 ```
elessair 0:f269e3021894 199
elessair 0:f269e3021894 200 ## Python coding rules & coding guidelines
elessair 0:f269e3021894 201 Some of our tools in tools are written in ```Python 2.7```. In case of developing tools for python we prefer to keep similar code styles across all Python source code. Please note that not all rules must be enforced. For example we do not limit you to 80 characters per line, just be sure your code can fit to widescreen display.
elessair 0:f269e3021894 202
elessair 0:f269e3021894 203 Please stay compatible with ```Python 2.7``` but nothing stops you to write your code so in the future it will by Python 3 friendly.
elessair 0:f269e3021894 204
elessair 0:f269e3021894 205 Please check our Python source code (especially ```test_api.py``` and ```singletest.py```) to get notion of how your new code should look like). We know our code is not perfect but please try to fit the same coding style to existing code so source looks consistent and is not series of different flavors.
elessair 0:f269e3021894 206
elessair 0:f269e3021894 207 Some general guidelines:
elessair 0:f269e3021894 208 * Use Python idioms, please refer to one of many on-line guidelines how to write Pythonic code: [Code Like a Pythonista: Idiomatic Python](http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html).
elessair 0:f269e3021894 209 * Please do not use TABs. Please use 4 spaces instead for indentations.
elessair 0:f269e3021894 210 * Please put space character between operators, after comma etc.
elessair 0:f269e3021894 211 * Please document your code, write comments and ```doc``` sections for each function or class you implement.
elessair 0:f269e3021894 212
elessair 0:f269e3021894 213 ### Static Code Analizers for Python
elessair 0:f269e3021894 214 If you are old-school developer for sure you remember tools like lint. "lint was the name originally given to a particular program that flagged some suspicious and non-portable constructs (likely to be bugs) in C language source code." Now lint-like programs are used to check similar code issues for multiple languages, also for Python. Please do use them if you want to commit new code to tools and other mbed SDK Python tooling.
elessair 0:f269e3021894 215
elessair 0:f269e3021894 216 Below is the list Python lint tools you may want to use:
elessair 0:f269e3021894 217
elessair 0:f269e3021894 218 * [pyflakes](https://pypi.python.org/pypi/pyflakes) - Please scan your code with pyflakes and remove all issues reported by it. If you are unsure if something should be modified or not you can skip lint report related fix and report this issue as possible additional commit in your pull request description.
elessair 0:f269e3021894 219
elessair 0:f269e3021894 220 * [pylint](http://www.pylint.org/) - Please scan your code with pylint and check if there are any issues which can be resolved and are obvious "to fix" bugs. For example you may forgot to add 'self' as first parameter in class method parameter list or you are calling unknown functions / functions from not imported modules.
elessair 0:f269e3021894 221
elessair 0:f269e3021894 222 * [pychecker](http://pychecker.sourceforge.net/) - optional, but more the merrier ;)
elessair 0:f269e3021894 223
elessair 0:f269e3021894 224 Example Python look&feel:
elessair 0:f269e3021894 225 ```python
elessair 0:f269e3021894 226 class HostRegistry:
elessair 0:f269e3021894 227 """ Class stores registry with host tests and objects representing them
elessair 0:f269e3021894 228 """
elessair 0:f269e3021894 229 HOST_TESTS = {} # host_test_name -> host_test_ojbect
elessair 0:f269e3021894 230
elessair 0:f269e3021894 231 def register_host_test(self, ht_name, ht_object):
elessair 0:f269e3021894 232 """ Registers (removes) host test by name from HOST_TESTS registry
elessair 0:f269e3021894 233 if host test is not already registered (check by name).
elessair 0:f269e3021894 234 """
elessair 0:f269e3021894 235 if ht_name not in self.HOST_TESTS:
elessair 0:f269e3021894 236 self.HOST_TESTS[ht_name] = ht_object
elessair 0:f269e3021894 237
elessair 0:f269e3021894 238 def unregister_host_test(self):
elessair 0:f269e3021894 239 """ Unregisters (removes) host test by name from HOST_TESTS registry.
elessair 0:f269e3021894 240 """
elessair 0:f269e3021894 241 if ht_name in HOST_TESTS:
elessair 0:f269e3021894 242 self.HOST_TESTS[ht_name] = None
elessair 0:f269e3021894 243
elessair 0:f269e3021894 244 def get_host_test(self, ht_name):
elessair 0:f269e3021894 245 """ Returns HOST_TEST if host name is valid.
elessair 0:f269e3021894 246 In case no host test is available return None
elessair 0:f269e3021894 247 """
elessair 0:f269e3021894 248 return self.HOST_TESTS[ht_name] if ht_name in self.HOST_TESTS else None
elessair 0:f269e3021894 249
elessair 0:f269e3021894 250 def is_host_test(self, ht_name):
elessair 0:f269e3021894 251 """ Function returns True if host name is valid (is in HOST_TESTS)
elessair 0:f269e3021894 252 """
elessair 0:f269e3021894 253 return ht_name in self.HOST_TESTS
elessair 0:f269e3021894 254 ```
elessair 0:f269e3021894 255
elessair 0:f269e3021894 256 ## Testing
elessair 0:f269e3021894 257 Please refer to TESTING.md document for detais regarding mbed SDK test suite and build scripts included in ```mbed/tools/```.
elessair 0:f269e3021894 258
elessair 0:f269e3021894 259 ## Before pull request checklist
elessair 0:f269e3021894 260 * Your pull request description section contains:
elessair 0:f269e3021894 261 * Rationale – tell us why you submitted this pull request. This is your change to write us summary of your change.
elessair 0:f269e3021894 262 * Description – describe changes you’ve made and tell us which new features / functionalities were implemented.
elessair 0:f269e3021894 263 * Manual / Cookbook / Handbook – you can put here manual, cookbook or handbook related to your change / enhancement. Your documentation can stay with pull request.
elessair 0:f269e3021894 264 * Test results (if applicable).
elessair 0:f269e3021894 265 * Make sure you followed project's coding rules and styles.
elessair 0:f269e3021894 266 * No dependencies are created to external C/C++ libraries which are not included already in our repository.
elessair 0:f269e3021894 267 * Please make sure that in your module all functions have unique prefix (no name space collisions).
elessair 0:f269e3021894 268 * You reused existing functionality, please do not add or rewrite existing code. E.g. use mbed’s ```FunctionPointer``` if possible to store your function pointers. Do not write another wrapper for it. We already got one. If some functionality is missing, just add it! Extend our APIs wisely!
elessair 0:f269e3021894 269 * Were you consistent? Please continue using style / code formatting, variables naming etc. in file they are modifying.
elessair 0:f269e3021894 270 * Your code compiles and links. Also doesn’t generate additional compilation warnings.