joey shelton / LED_Demo2

dhgdh

Dependencies:   MAX44000 PWM_Tone_Library nexpaq_mdk

Fork of LED_Demo by joey shelton

mbd_os/docs/COMMITTERS.md@9:6bb35cef007d, 2016-10-22 (annotated)

Committer:
cyberjoey
Date:
Sat Oct 22 01:31:58 2016 +0000
Revision:
9:6bb35cef007d
Parent:
1:55a6170b404f 
WORKING

Who changed what in which revision?

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