Greg Steiert / pegasus_dev

Development mbed library for MAX32630FTHR

Dependents:   blinky_max32630fthr

docs/COMMITTERS.md@0:5c4d7b2438d3, 2016-11-11 (annotated)

Committer:
switches
Date:
Fri Nov 11 20:59:50 2016 +0000
Revision:
0:5c4d7b2438d3
Initial commit

Who changed what in which revision?

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