1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
*****************
How to contribute
*****************
So you want to contribute to the Powerline project? Awesome! This document
describes the guidelines you should follow when making contributions to the
project.
**Please note that these guidelines aren't mandatory in any way, but your
pull request will be merged a lot faster if you follow them.**
Getting started
===============
* Make sure you have a `GitHub account <https://github.com/signup/free>`_.
* Submit an `issue on GitHub <https://github.com/powerline/powerline/issues>`_,
assuming one does not already exist.
* Clearly describe the issue.
* If the issue is a bug: make sure you include steps to reproduce, and
include the earliest revision that you know has the issue.
* Fork the repository on GitHub.
Making changes
==============
* Create a topic branch from where you want to base your work.
* Powerline uses the `Git Flow
<http://nvie.com/posts/a-successful-git-branching-model/>`_ branching
model.
* Most contributions should be based off the ``develop`` branch.
* Prefix your branch with ``feature/`` if you're working on a new feature.
* Include the issue number in your topic branch, e.g.
``321-fix-some-error`` or ``feature/123-a-cool-feature``.
* Make commits of logical units.
* Run your code through ``flake8`` and fix any programming style errors. Use
common sense regarding whitespace warnings, not all warnings need to be
fixed.
* Make sure your commit messages are in the `proper format
<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.
The summary must be no longer than 70 characters. Refer to any related
issues with e.g. ``Ref #123`` or ``Fixes #234`` at the bottom of the
commit message. Commit messages can use Markdown with the following
exceptions:
* No HTML extensions.
* Only indented code blocks (no ``````` blocks).
* Long links should be moved to the bottom if they make the text wrap or
extend past 72 columns.
* Make sure you have added the necessary tests for your changes.
* Run *all* the tests to assure nothing else was accidentally broken.
Programming style
-----------------
* The project uses *tabs for indentation* and *spaces for alignment*, this
is also included in a vim modeline on top of every script file.
* Run your code through ``flake8 --ignore=W191,E501,E128,W291,E126,E101`` to fix
any style errors. Use common sense regarding whitespace warnings, not all
``flake8`` warnings need to be fixed.
* Trailing whitespace to indicate a continuing paragraph is OK in comments,
documentation and commit messages.
* It is allowed to have too long lines. It is advised though to avoid lines
wider then a hundred of characters.
* Imports have the following structure:
1. Shebang and modeline in a form
.. code-block:: python
#!/usr/bin/env python
# vim:fileencoding=utf-8:noet
. Modeline is required, shebang is not. If shebang is present file must end
with
.. code-block:: python
if __name__ == '__main__':
# Actual script here
2. Module docstring.
3. ``__future__`` import exactly in a form
.. code-block:: python
from __future__ import (unicode_literals, division, absolute_import, print_function)
(powerline.shell is the only exception due to problems with argparse). It
is not separated by newline with shebang and modeline, but is with
docstring.
4. Standard python library imports in a form ``import X``.
5. Standard python library imports in a form ``from X import Y``.
6. Third-party (non-python and non-powerline) library imports in a form
``import X``.
7. Third-party library imports in a form ``from X import Y``.
8. Powerline non-test imports in a form ``from powerline.X import Y``.
9. Powerline test imports in a form ``import tests.vim as vim_module``.
10. Powerline test imports in a form ``from tests.X import Y``.
Each entry is separated by newline from another entry. Any entry except for
the first and third ones is optional. Example with all entries:
.. code-block:: python
#!/usr/bin/env python
# vim:fileencoding=utf-8:noet
'''Powerline super module'''
from __future__ import (unicode_literals, division, absolute_import, print_function)
import sys
from argparse import ArgumentParser
import psutil
from colormath.color_diff import delta_e_cie2000
from powerline.lib.unicode import u
import tests.vim as vim_module
from tests import TestCase
Submitting changes
==================
* Push your changes to a topic branch in your fork of the repository.
* If necessary, use ``git rebase -i <revision>`` to squash or reword commits
before submitting a pull request.
* Submit a pull request to `powerline repository
<https://github.com/powerline/powerline>`_.
|
