Skip to content

Commit e2a1139

Browse files
AdrianzatreanuAdrianzatreanu
committed
Move docs from coala
1 parent 8400586 commit e2a1139

29 files changed

+4406
-0
lines changed

‎Getting_Involved/Codestyle.rst

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
Codestyle for *coala*
2+
=====================
3+
4+
*coala* follows the `PEP8
5+
codestyle <https://www.python.org/dev/peps/pep-0008/>`__ with a maximum
6+
line length of 80 characters including newline. Invoke ``coala`` to let
7+
it correct your code automatically.
8+
9+
Additional Style Guidelines
10+
---------------------------
11+
12+
Documentation Comments
13+
~~~~~~~~~~~~~~~~~~~~~~
14+
15+
A documentation comment consists of 2 parts - the description of what
16+
the function/class/module does followed by the parameters it takes in,
17+
the return value it gives out and the exceptions it can raise.
18+
19+
Nothing should be written on the first and last line where the docstring
20+
begins and ends, and a newline should separate the description and the
21+
rest. Each message in the documentation comment must end with a
22+
full-stop. Also the description of all arguments and the return value
23+
should begin at the same column.
24+
25+
Example:
26+
27+
::
28+
29+
def area(length, breadth):
30+
"""
31+
Finds the area of a rectangle of the given length and breadth.
32+
33+
:param length: The length of the rectangle.
34+
:param breadth: The breadth of the rectangle.
35+
:return: The area of the rectangle.
36+
:raises ValueError: Raises ValueError if the arguments are not of type
37+
float or int.
38+
"""
39+
40+
If the description for a param or other keywords exceeds 1 line,
41+
continue it in the next. Make sure that the second line is aligned Below
42+
the first line.
43+
44+
Example :
45+
46+
::
47+
48+
:param something: A very long line describing the variable something
49+
in great detail.
50+
:return: This message also started in the same column and it
51+
starts again at the same column as the rest of the
52+
messages.
53+
54+
Type Checking
55+
~~~~~~~~~~~~~
56+
57+
If you want to assure that parameters have a certain type, you can use
58+
the ``enforce_signature`` decorator and simply annotate your function
59+
with the allowed types:
60+
61+
.. code:: python
62+
63+
@enforce_signature
64+
def concatenate_strings(a: str, b: str, c: (str, None)=None):
65+
if c is None:
66+
c = ""
67+
return a + b + c
68+
69+
This will raise a ``TypeError`` if ``a``, ``b`` or ``c`` are no strings
70+
and ``c`` is not ``None``.

‎Getting_Involved/MAC_Hints.rst

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
Coverage Installation Hints for OSX Users:
2+
==========================================
3+
4+
1. Make sure you have installed Xcode and Homebrew.
5+
---------------------------------------------------
6+
7+
2. Install Python3.
8+
-------------------
9+
10+
::
11+
12+
$ brew search python # This should display python3
13+
$ brew install python3
14+
$ python3 --version # To check the installed version
15+
16+
3. Create Virtual environments with pyvenv
17+
------------------------------------------
18+
19+
::
20+
21+
# Create Virtual Env named myenv
22+
$ pyvenv myenv
23+
24+
# This will create a folder named myenv in the
25+
# current directory. To activate this environment just type
26+
$ source myenv/bin/activate
27+
28+
# You can start Python3 by typing:
29+
$ python
30+
31+
4. Virtualenvwrapper with Python 3:
32+
-----------------------------------
33+
34+
::
35+
36+
# Installation
37+
$ pip3 install virtualenv
38+
$ pip3 install virtualenvwrapper
39+
40+
# Folder to contain Virtual Environments
41+
$ mkdir ~/.virtualenvs
42+
43+
# Add the following in ~/.bash_profile
44+
$ export WORKON_HOME=~/.virtualenvs
45+
$ source /usr/local/bin/virtualenvwrapper.sh
46+
47+
# Activate Changes
48+
$ source ~/.bash_profile
49+
50+
# Get Python3 path (python3_pth)
51+
$ where python3
52+
53+
# Create a new virtual environment with Python3
54+
$ mkvirtualenv --python=python3_path myenv
55+
56+
Finally!
57+
--------
58+
59+
::
60+
61+
# Install python-coverage3 by
62+
$ easy_install coverage
63+

‎Getting_Involved/Newcomers.rst

+147
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
.. _newcomer-guide:
2+
3+
Welcome to the Newcomers guide!
4+
===============================
5+
6+
This guide will help you to get involved and teach you how to make your first
7+
contribution to *coala*!
8+
9+
Meet the community!
10+
-------------------
11+
12+
To get started, the first step is to meet the community. We use gitter to
13+
communicate, and there the helpful community will guide you.
14+
Join us at `coala gitter <https://gitter.im/coala-analyzer/coala/>`_.
15+
The newcomers should ping us "Hello World" to let us know they are here
16+
because we care!
17+
18+
**Congratulations!** You are now part of our community.
19+
20+
Start working
21+
-------------
22+
23+
Let us know that you are interested in contributing on gitter and ask for an
24+
invitation to our org. This is your first step towards contributing.
25+
The invitation will be sent by mail and you will have to accept
26+
it to join. If you don't find the invitation, accept it `here <https://github.com/coala-analyzer>`_.
27+
28+
Now that you are part of our organization, you can start working on issues.
29+
If you are familiar with git, you can skip the next section and pick an issue.
30+
31+
32+
Get help with git
33+
-----------------
34+
35+
We use GitHub to manage our repository. If you're not familiar with git, we
36+
strongly recommend following a tutorial, such as `this one <https://try.github.io/levels/1/challenges/1>`_.
37+
38+
If there's anything unclear, or you are encountering problems, feel free
39+
to contact us on gitter, and we will help you!
40+
41+
Picking up an issue
42+
-------------------
43+
44+
Now is the time to pick an issue.
45+
Here is the link that will lead you to `Newcomers issues <http://tinyurl.com/coala-new>`_.
46+
47+
.. seealso::
48+
49+
For more information about what bears are, please check the following link: `Writing bears <http://coala.readthedocs.org/en/latest/Users/Tutorials/Writing_Bears.html>`_
50+
51+
The easy issues that will help you get started are labeled as
52+
"difficulty/newcomer" and are only there to give you a glimpse of how it is
53+
to work with us.
54+
55+
Now pick an issue which isn't assigned, and if you want to fix
56+
it, then leave a comment that you would like to get assigned. This way
57+
we don't have multiple people working on the same issue at the same time.
58+
Now you can start working on it.
59+
For more info on how to work correctly with git, try `this <http://coala.readthedocs.org/en/latest/Users/Tutorials/Git_Help.html>`_.
60+
61+
.. note::
62+
63+
Before starting to write your first commit, check out this link:
64+
`Writing good commits <http://coala.readthedocs.org/en/latest/Getting_Involved/Writing_Good_Commits.html>`_
65+
66+
Things to do before pushing
67+
---------------------------
68+
69+
Now you need to make sure your change is actually working. For this, you will
70+
need to test it locally before pushing it to your fork, and checking it with
71+
concrete examples. So basically, run tests and run *coala* by simply typing
72+
73+
::
74+
75+
$ coala
76+
77+
into your bash. This will analyze your code and help you fix it.
78+
79+
.. seealso::
80+
81+
`Executing tests <http://coala.readthedocs.org/en/latest/Getting_Involved/Testing.html>`_
82+
83+
Sending your changes
84+
--------------------
85+
86+
Now that you've fixed the issue, you've tested it and you think it is ready
87+
to be used, create a commit and push it to your fork, using:
88+
89+
::
90+
91+
$ git push origin fix-branch
92+
93+
Creating a ``Pull Request``
94+
---------------------------
95+
96+
Now that your commit has been sent to your fork, it is time
97+
to do a ``Pull Request``. It can be done by accessing your fork on GitHub and
98+
clicking ``New Pull Request``.
99+
100+
**Congratulations!** You have now created your first ``Pull Request``!
101+
102+
If you know you have more work to do on this pull request before it is
103+
ready to be accepted, you can optionally indicate this to other
104+
developers by starting your pull request title with "wip"
105+
(case-insensitive).
106+
107+
What to do after creating a ``Pull Request``
108+
--------------------------------------------
109+
110+
After creating your ``Pull Request``, there's two options:
111+
112+
- your ``Pull Request`` gets accepted, and your commit will get merged into the
113+
master branch
114+
- your ``Pull Request`` doesn't get accepted, and therefore you will
115+
need to to modify it as per the review comments
116+
117+
It's highly unlikely that your ``Pull Request`` will be accepted on the first
118+
attempt - but don't worry, that's just how it works. It helps us maintain
119+
*coala* **clean** and **stable**.
120+
121+
.. seealso::
122+
123+
`Review Process <http://coala.readthedocs.org/en/latest/Getting_Involved/Review.html>`_.
124+
125+
Now if you need to modify your code, you can simply edit it again, add it and
126+
commit it using
127+
128+
::
129+
130+
$ git commit -a --amend
131+
132+
This will edit your last commit message. If your commit message was considered
133+
fine by our reviewers, you can simply send it again like this. If not, edit it
134+
and send it. You have successfully edited your last commit!
135+
136+
.. note::
137+
138+
Don't forget! After editing your commit, you will have to push it again.
139+
This can be done using:
140+
141+
::
142+
143+
$ git push --force origin
144+
145+
**Congratulations!** Your PR just got accepted! You're awesome.
146+
Now try `writing a bear <http://coala.readthedocs.org/en/latest/Users/Tutorials/Writing_Bears.html>`_,
147+
they are really rewarding!

‎Getting_Involved/README.rst

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
Getting Involved
2+
================
3+
4+
We are working hard to make *coala* reality. If you want to help us you
5+
can do the following things:
6+
7+
- Join us on our mailing list.
8+
- *coala* developer list:
9+
https://groups.google.com/forum/#!forum/coala-devel
10+
11+
- [email protected]
12+
13+
- *coala* announcement list:
14+
https://groups.google.com/forum/#!forum/coala-announcements
15+
16+
- [email protected]
17+
18+
- Join us on our developer chatroom:
19+
https://gitter.im/coala-analyzer/coala
20+
- Run our tests. Just follow the instructions on the
21+
:doc:`Testing <../Getting_Involved/Testing>` page. Report back to us if
22+
anything goes wrong unexpectedly.
23+
- Give us feedback. If you think we're doing something useless or
24+
useful with some specific things, please write us! We are interested
25+
in your needs and favors so you get the highest possible quality.
26+
- Drive bug discussions. Just state your opinion, everywhere!
27+
- Review code. Get a glance at what we're doing and say something if
28+
you don't understand something or think we're doing something wrong.
29+
- Write documentation. If you need some additional information for
30+
documenting feel free to ask us!
31+
- Write code. Usually code we need is indicated through bug reports.
32+
Please get in contact with us so we can coordinate coding together.
33+
34+
Please take a look at the other files in this directory for getting
35+
started with specific parts of *coala*.
36+
37+
We appreciate any help. (Partially with words, partially with chocolate
38+
if you live near hamburg.)
39+
40+
Modularity, clean good code as well as a high usability for both users
41+
and developers of analyse routines (called bears) stand in the
42+
foreground of the development. We will not speed up our development if
43+
it needs sacrificing any aspect of quality.

0 commit comments

Comments
 (0)