|
| 1 | +# Contributing to LiveCode |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | +Copyright © 2003-2015 LiveCode Ltd., Edinburgh, UK |
| 6 | + |
| 7 | +## Contributors' forums |
| 8 | + |
| 9 | +General discussion about contributing to the LiveCode Community open-source projects takes place on the [LiveCode Open Source forums](http://forums.livecode.com/viewforum.php?f=65), and in particular the [Engine Contributors forum](http://forums.livecode.com/viewforum.php?f=66). |
| 10 | + |
| 11 | +## Contributor's License Agreement (CLA) |
| 12 | + |
| 13 | +If you wish to contribute to development of LiveCode, you must sign the [Contributor's Agreement](http://livecode.com/account/developer/contribute). This agreement is required because the LiveCode project is dual-licensed both under the GPLv3 and a commercial (closed-source) license; you need to give LiveCode Ltd. permission to use your submissions in this way. |
| 14 | + |
| 15 | +**Note:** LiveCode cannot accept any pull-requests from individuals who have not signed this agreement. |
| 16 | + |
| 17 | +## Using GitHub |
| 18 | + |
| 19 | +The LiveCode workflow is a typical git workflow, where contributors fork the [runrev/livecode](https://github.com/runrev/livecode) repository, make their changes on a branch, and then submit a pull request. |
| 20 | + |
| 21 | +### Setting up git with your user information |
| 22 | + |
| 23 | +Please ensure that your full name and e-mail address are in the git configuration. Ideally, the e-mail address you use with git should be the same as the e-mail address you used to sign the CLA (i.e. the one used for your LiveCode customer account). |
| 24 | + |
| 25 | +You can set up the name and e-mail address from the command line: |
| 26 | + |
| 27 | + git config --global user.name "<your name>" |
| 28 | + git config --global user.email "<your email address>" |
| 29 | + |
| 30 | +**Note**: Pull requests which add commits containing incorrect author name and e-mail addresses will be rejected. |
| 31 | + |
| 32 | +### Branches in GitHub |
| 33 | + |
| 34 | +You should base your changes on an appropriate branch: |
| 35 | + |
| 36 | +* The `develop` branch is where work on the next major, experimental release of LiveCode takes place. It usually has all of the most exciting new features, but also a lot of bugs to go with them. If you are adding a new feature to LiveCode, submit your changes to this branch. |
| 37 | + |
| 38 | +* The `develop-X.Y` branches work towards the next X.Y.Z release. They are usually much more stable than the `develop` branch. If you are fixing a bug in LiveCode, submit your changes to the "oldest" `develop-X.Y` branch that exhibits the bug. |
| 39 | + |
| 40 | +* The `release-X.Y` branches are used as part of the release process. Unless you are helping to make a release, you should not normally work with these branches. |
| 41 | + |
| 42 | +### Creating a pull request |
| 43 | + |
| 44 | +When you submit a pull request, please make sure to follow the following steps: |
| 45 | + |
| 46 | +1. Ensure that all the commits have good log messages, in the following format: |
| 47 | + |
| 48 | + ``` |
| 49 | + Summary line of less than 80 characters |
| 50 | +
|
| 51 | + Explanation of what the commit fixes and why it's the right |
| 52 | + fix, possibly using multiple paragraphs. For example, you |
| 53 | + might want to describe other options and why the one you |
| 54 | + chose is better. |
| 55 | + ``` |
| 56 | + |
| 57 | + It's very important that readers can get a good idea of what the commit is about just by reading the summary line. To help with this, we use some special "tags" at the start of a commit message summary line: |
| 58 | + |
| 59 | + * If the commit fixes a bug, please add `[[Bug <bug number>]]` at the start. |
| 60 | + |
| 61 | + * If the commit relates to a particular new feature — and there are several commits and pull requests involved in the feature — please add `[<feature-name>]` at the start. |
| 62 | + |
| 63 | + * If the commit fixes a [Coverity Scan defect](https://scan.coverity.com/projects/4036), please add `[CID <defect number>]` at the start. |
| 64 | + |
| 65 | +2. Make sure that the pull request only relates to *one* change (one bug fix, one new feature, etc.) or to a group of very closely-related fixes. Please make sure that the pull request has a good description too (often you can base the title and body of the pull request on the commit messages). |
| 66 | + |
| 67 | + Please highlight any areas of your changes that you thought were particularly difficult to figure out. This will help make sure that your code gets thoroughly reviewed. |
| 68 | + |
| 69 | +### Pull request process |
| 70 | + |
| 71 | +After you submit a pull request, a member of the LiveCode team will review your changes. They will probably find some improvements that need to be made. Please note that if a reviewer asks you to change your code, it doesn't necessarily mean that there was anything wrong with the changes you've made. It often means that they have spotted a way to fix other things at the same time, or to make your change fit in better with other things that are being worked on elsewhere. |
| 72 | + |
| 73 | +Once a reviewer is happy with the changes, they will mark the pull request as reviewed. The LiveCode continuous integration system will then take your code, and automatically build & test it on all of the platforms supported by LiveCode. |
| 74 | + |
| 75 | +If the tests don't pass, then you will need to make some more changes to fix the problems that were found. These will then be reviewed, etc. |
| 76 | + |
| 77 | +Once your changes have been reviewed and tested, they will be merged in time for the next release. |
| 78 | + |
| 79 | +## Bugs |
| 80 | + |
| 81 | +Finding and fixing bugs in LiveCode is a particularly valuable contribution. |
| 82 | + |
| 83 | +If you've found a bug, please add a ticket to the [LiveCode issue tracking system](http://quality.runrev.com/). This will give you a bug number which can be used whenever discussing the issue, and included in git commit log messages and in GitHub pull request descriptions. This will help other contributors keep track of who's working on what. |
| 84 | + |
| 85 | +When you submit a pull request that fixes a bug, the status of the bug should be set to "AWAITING_MERGE" -- please also add a comment to the bug with a link to the pull request's page. |
| 86 | + |
| 87 | +When the pull request is merged, the status should be set to "AWAITING_BUILD". |
| 88 | + |
| 89 | +## Coding style |
| 90 | + |
| 91 | +### C++ coding style |
| 92 | + |
| 93 | +The majority of the engine is written in C++, but the style treats C++ as an improved version of C, and doesn't use the whole of the language's feature set. In particular: |
| 94 | + |
| 95 | +* The engine doesn't use exceptions or RTTI (run time type information). |
| 96 | +* Templates are used sparingly, and typically as "sanitized macros" for efficiency purposes or for resource management. |
| 97 | +* No standard C++ library is used (i.e. you cannot use anything in the `std` namespace) |
| 98 | + |
| 99 | +#### Naming convention |
| 100 | + |
| 101 | +The engine source code follows a standard naming convention. |
| 102 | + |
| 103 | +Variable and function names should be descriptive. Don't be scared of verbosity (but don't go too overboard on symbol lengths) |
| 104 | + |
| 105 | + |
| 106 | +Variable names: |
| 107 | +* should be lowercase, with words separated by underscores ("\_") |
| 108 | +* should be prefixed to indicate scope: |
| 109 | + * "t\_": local variables |
| 110 | + * "p\_": in parameters |
| 111 | + * "r\_": out parameters |
| 112 | + * "x\_": in-out parameters |
| 113 | + * "m\_": class or struct instance member variables |
| 114 | + * "s\_": class, function, or file-local static variables |
| 115 | + * "g\_": global variables |
| 116 | + * example: `t_foo_bar` |
| 117 | + |
| 118 | +Constants' names (including enum members): |
| 119 | +* should be camel-case |
| 120 | +* should prefixed with `kMC` and the module name |
| 121 | +* example: `kMCModuleFooBar` |
| 122 | + |
| 123 | +Function names: |
| 124 | +* should generally be camel-case |
| 125 | +* public / exported functions should have names prefixed with "MC" followed by the module name. |
| 126 | +* file-local static functions may also be in lower-case and underscore-separated |
| 127 | +* example: `MCFooBar()` |
| 128 | + |
| 129 | +#### Coding practices |
| 130 | + |
| 131 | +* Declare and initialize local variables on separate lines |
| 132 | +* Initialize all variables to a base value, e.g. |
| 133 | + * pointers to `nil` |
| 134 | + * bools to `true` or `false` |
| 135 | + * numbers to 0 |
| 136 | +* Only pass `bool` values to conditions (e.g. `if`, `while`, etc.). Don't assume that `nil`/`null`/`0` are false. |
| 137 | +* Always check the success of memory allocations; if the calling code can't handle memory failure then prefix the line that allocates with `/* UNCHECKED */` |
| 138 | +* Avoid using preprocessor macros to abbreviate code; use inline and/or template functions instead |
| 139 | +* Use implicit resource management (e.g. `MCAutoStringRef`) wherever reasonably possible |
| 140 | +* Functions should not modify "out" function parameters until immediately before returning, and only on success |
| 141 | +* `goto` is only usually acceptable for implementing cleanup-on-error |
| 142 | +* Avoid using the ternary operator (`<condition> ? <expr-if-true> : <expr-if-false>`) |
| 143 | +* Use a bit-field when declaring boolean values in a struct or class (e.g. `bool m_bool_member : 1`) |
| 144 | +* Whenever adding a function, add a comment that explains precisely: |
| 145 | + * What the function does, under what conditions it succeeds, and how it behaves when it fails |
| 146 | + * What the function expects as inputs, and what outputs it generates |
| 147 | + |
| 148 | +#### Layout and style |
| 149 | + |
| 150 | +* Indent with tabs, using a 4-space tab width. |
| 151 | +* All curly braces should be on a line on their own. They should be indented to match the level of the construct they relate to. For example: |
| 152 | + |
| 153 | + ```` |
| 154 | + if (/* <condition> */) |
| 155 | + { |
| 156 | + /* <body> */ |
| 157 | + } |
| 158 | + ```` |
| 159 | +* Use a single space after the `for`, `while`, `if`, and `switch` keywords, as in the example above. |
| 160 | +* Don't insert a space between a function or macro name and its parameter list |
| 161 | +* Insert a single space after each comma (",") |
| 162 | +* Insert a single space before and after binary operators (e.g. `x == y`) |
| 163 | +* Put a single statement on each line |
| 164 | +* Split overly-long lines (> 80 characters) appropriately. Try to place a line-break after any binary operators or commas. |
| 165 | +* Use a single blank line to separate different areas of code with in a function. |
| 166 | +* Use a single blank line between function and type definitions |
| 167 | +* Separate significant areas of code with comment bars, e.g. a line containing only 80 slash characters ("/") |
0 commit comments