|
| 1 | +# Contributing Guidelines |
| 2 | + |
| 3 | +Thanks for interest in contributing to MTF. |
| 4 | + |
| 5 | +The following is a set of guidelines for contributing to MTF. These are not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. |
| 6 | + |
| 7 | +## How to contribute to MTF |
| 8 | + |
| 9 | +### Reporting Bugs |
| 10 | + |
| 11 | +Before creating bug reports, please check a [list of known issues](https://github.com/fedora-modularity/meta-test-family/issues) to see if the problem has already been reported. |
| 12 | + |
| 13 | +If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/fedora-modularity/meta-test-family/issues/new). Be sure to include a **descriptive title, clear description and a package version** and please include **as many details as possible** to help maintainers reproduce the issue and resolve it faster. If possible, add a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring. |
| 14 | + |
| 15 | +> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. |
| 16 | +
|
| 17 | +### Suggesting Enhancements |
| 18 | + |
| 19 | +Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). When you are creating an enhancement issue, **use a clear and descriptive title** and **provide a clear description of the suggested enhancement** in as many details as possible. |
| 20 | + |
| 21 | +### Submitting changes |
| 22 | + |
| 23 | +To submit changes, please send a [GitHub Pull Request](https://github.com/fedora-modularity/meta-test-family/pull/new/devel). Before submitting a PR, please **read the [Styleguides](#styleguides)** to know more about coding conventions used in this project. Also we will appreciate if you **check your code with pylint and pyflakes**. Always **create a new branch for each pull request** to avoid intertwingling different features or fixes on the same branch. Always **do "git pull --rebase" and "git rebase"** vs "git pull" or "git merge". |
| 24 | + |
| 25 | +> **Note:** We are aware of [current syntax and style code errors](https://github.com/fedora-modularity/meta-test-family/issues/21) and working on fixing them. |
| 26 | +
|
| 27 | +## Styleguides |
| 28 | + |
| 29 | +### Git Commit Messages |
| 30 | + |
| 31 | + * Use the present tense ("Add feature" not "Added feature") |
| 32 | + * Use the imperative mood ("Move cursor to..." not "Moves cursor to...") |
| 33 | + * Limit the first line to 72 characters or less |
| 34 | + |
| 35 | + ``` |
| 36 | + $ git commit -m "A brief summary of the commit |
| 37 | + > |
| 38 | + > A paragraph describing what changed and its impact." |
| 39 | + ``` |
| 40 | +
|
| 41 | + * Reference issues and pull requests liberally after the first line |
| 42 | + * When only changing documentation, include `[ci skip]` in the commit description |
| 43 | + * Consider ending the commit message with an applicable emoji: |
| 44 | + * :tada: `:tada:` initial commit |
| 45 | + * :bookmark: `:bookmark:` version tag |
| 46 | + * :construction: `:construction:` work in progress (WIP) |
| 47 | + * :package: `:package:` release |
| 48 | + * :art: `:art:` improvement of the format/structure of the code |
| 49 | + * :racehorse: `:racehorse:` performance improvement |
| 50 | + * :hatched_chick: `:hatched_chick:` new feature |
| 51 | + * :book: `:book:` docs update |
| 52 | + * :bug: `:bug:` bugfix |
| 53 | + * :pencil2: `:pencil2:` typo fix |
| 54 | + * :recycle: `:recycle:` remove code or files |
| 55 | + * :green_heart: `:green_heart:` CI build fix |
| 56 | + * :white_check_mark: `:white_check_mark:` add tests |
| 57 | + * :arrow_up: `:arrow_up:` dependencies upgrade |
| 58 | + * :arrow_down: `:arrow_down:` dependencies downgrade |
| 59 | + * :exclamation: `:exclamation:` important |
| 60 | +
|
| 61 | +### Codding guidelines |
| 62 | +
|
| 63 | +We don't think much of this should be too strange to readers familiar with contributing to Python projects, though it helps if we all get on the same page. |
| 64 | +
|
| 65 | +MTF project uses [Landscape tool](https://landscape.io/github/fedora-modularity/meta-test-family/49) to check every commit for errors. |
| 66 | +
|
| 67 | +[PEP 8](https://www.python.org/dev/peps/pep-0008/) is a great Python style guide, which we try to follow. |
| 68 | +
|
| 69 | +#### Licenses |
| 70 | +
|
| 71 | + * Every file should have a license header, including the copyright of the original author. |
| 72 | +
|
| 73 | +#### Python Imports |
| 74 | +
|
| 75 | + * To make it clear what is importing, imports should not be sprinkled throughout the code, but happen at the top of the file. |
| 76 | +
|
| 77 | +#### Comments |
| 78 | +
|
| 79 | + * Readability is one of the most important goals for this project |
| 80 | + * Comment any non-trivial code where someone might not know why you are doing something in a particular way |
| 81 | + * Though if something should be commented, that's often a sign someone should write a function |
| 82 | + * All new functions must have a basic docstring comment |
| 83 | + * Commenting above a line is preferable to commenting at the end of a line |
| 84 | +
|
| 85 | +#### Whitespace |
| 86 | +
|
| 87 | + * Four space indent is strictly required |
| 88 | + * Include meaningful whitespace between lines of code |
| 89 | +
|
| 90 | +#### Variables |
| 91 | +
|
| 92 | + * Use descriptive variable names instead of variables like 'x, y, a, b, foo' |
| 93 | + * MTF python code uses identifiers like 'ClassesLikeThis and variables_like_this |
| 94 | +
|
| 95 | +#### Classes |
| 96 | +
|
| 97 | + * It is desirable to see classes in their own files. |
| 98 | + * Classes should generally not cause side effects as soon as they are instantiated, move meaningful behavior to methods rather than constructors. |
| 99 | +
|
| 100 | +#### Functions and Methods |
| 101 | +
|
| 102 | + * In general, functions should not be 'too long' and should describe a meaningful amount of work |
| 103 | + * When code gets too nested, that's usually the sign the loop body could benefit from being a function |
| 104 | + * Parts of our existing code are not the best examples of this at times. |
| 105 | + * Functions should have names that describe what they do, along with docstrings |
| 106 | + * Functions should be named with_underscores |
| 107 | + * "Don't repeat yourself" is generally a good philosophy |
| 108 | +
|
| 109 | +#### Exceptions |
| 110 | +
|
| 111 | + * In the main body of the code, use typed exceptions where possible: |
| 112 | +
|
| 113 | + ``` |
| 114 | + # not this |
| 115 | + raise Exception("panic!") |
| 116 | +
|
| 117 | + # this |
| 118 | + from moduleframework.exceptions import SomeTypedException |
| 119 | + ... |
| 120 | + raise SomeTypedException("panic!") |
| 121 | + ``` |
| 122 | +
|
| 123 | + * Similarly, exception checking should be fine grained: |
| 124 | +
|
| 125 | + ``` |
| 126 | + # not this |
| 127 | + try: |
| 128 | + foo() |
| 129 | + except: |
| 130 | + bar() |
| 131 | +
|
| 132 | + # but this |
| 133 | + try: |
| 134 | + foo() |
| 135 | + except SomeTypedException: |
| 136 | + bar() |
| 137 | + ``` |
| 138 | +
|
| 139 | +## Questions? |
| 140 | +
|
| 141 | +* Ask any question about how to use MTF in the [#fedora-modularity](https://webchat.freenode.net/?channels=fedora-modularity) chat channel on freenode IRC. |
| 142 | +
|
| 143 | +Thank you! :heart: :heart: :heart: |
| 144 | +
|
| 145 | +MTF Team |
0 commit comments