Added contribution guidelines.
This commit is contained in:
parent
a73d872825
commit
3ed5a86c46
90
CONTRIBUTING.rst
Normal file
90
CONTRIBUTING.rst
Normal file
@ -0,0 +1,90 @@
|
||||
=========================
|
||||
Contributing to magnetico
|
||||
=========================
|
||||
|
||||
Hello there! We would be glad to accept your contributions and this is document is a guide to help you throughout the
|
||||
process of contributing.
|
||||
|
||||
Kinds of Contributions
|
||||
======================
|
||||
There are several kinds of contributions and feel free to choose ones that you feel most comfortable with:
|
||||
|
||||
1. Programming
|
||||
|
||||
If you are a **Python** programmer, great! **JavaScript** programmers are too welcome. **magneticod** and
|
||||
**magneticow** are programmed in Python 3, and we use a tiny tiny bit of JavaScript for the web interface offered by
|
||||
**magneticow**. We are trying to keep the amount of JavaScript used to the bare minimum (so that users with NoScript
|
||||
and JavaScript disabled can still use it), so if your contribution is refused, please do not take it personally.
|
||||
|
||||
2. Testing
|
||||
|
||||
**magnetico** is still a pre-v1.0 software, hence is considered unstable. Currently, developers are testing
|
||||
**magnetico** themselves before each version and this is a very tiresome task. Also, due to lack of resources and
|
||||
diversity of different setups we have, we cannot test **magnetico** extensively. If you would like to test
|
||||
**magnetico** for us, we would be grateful.
|
||||
|
||||
3. User Interface Design & User Experience
|
||||
|
||||
**magnetico** is not the first DHT search engine, but "the first autonomous (self-hosted) BitTorrent DHT search
|
||||
engine suite that is designed **for end-users**." We care about *end-users* and value their experience while using
|
||||
**magnetico** suite. Ease of installation, and of use are our primary concerns and any contributions to improve these
|
||||
experiences are much welcome.
|
||||
|
||||
Things Every Contributor Should Know
|
||||
====================================
|
||||
* Join `magnetico-dev gitter channel <https://gitter.im/magnetico-dev/magnetico-dev>`_ to join the conversation. We
|
||||
value every opinion.
|
||||
* Let people know what you are planning to do, especially before undertaking a huge task. It is very discouraging to
|
||||
spend your time on a daunting task and to see it refused. Asking people before acting would prevent such situations
|
||||
and easier for both parties to be prepared.
|
||||
* Do not argue against the first principles of the project. The **magnetico** project is not just a piracy tool or
|
||||
whatever you think it to be, but it is a **self-hosted** DHT search engine, to serve as another core component of the
|
||||
BitTorrent network, to resist censorship and protect users' privacy. Any attempt to violate these principles in favour
|
||||
of anything else (which you might think to be more *practical*) will be firmly refused.
|
||||
|
||||
Python Coding Guidelines
|
||||
========================
|
||||
.. image:: https://api.travis-ci.org/boramalper/magnetico.svg?branch=master
|
||||
:target: https://travis-ci.org/boramalper/magnetico
|
||||
|
||||
* In general, we follow `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ and
|
||||
`Google Python Style Guide <https://google.github.io/styleguide/pyguide.html>`_.
|
||||
* Prefer this document over Google Python Style Guide over PEP 8 in case of conflict.
|
||||
|
||||
|
||||
|
||||
* Maximum line length is 120 characters.
|
||||
* Do not abbreviate variable names, unless the abbreviation is famous (even though it might be *obvious* in its code
|
||||
context). For instance, `HTTP` is accepted but `_f` for *futures* and `p_` for *parent* are NOT.
|
||||
* A possible exception of this rule is to use shorter names in case of complex symbolic manipulation and/or
|
||||
operations, for instance in complex for-loops, functions etc. Shorter names would allow the programmer to follow the
|
||||
flow of the operations and logic behind the manipulation more easily and hence justified. But, comments are required
|
||||
in those cases.
|
||||
* Do NOT use shebang line to specify the interpreter or the encoding of the file. The former is handled by the Python's
|
||||
setuptools and latter is UTF-8, for every and each source file.
|
||||
* Prefer Python standard library over 3rd party solutions, unless justified.
|
||||
|
||||
|
||||
|
||||
* We use `Travis CI <https://travis-ci.org/boramalper/magnetico>`_ to automatically run tests on the latest code. We use
|
||||
|
||||
* `pylint <https://www.pylint.org/>`_
|
||||
* `mypy <http://mypy-lang.org/>`_
|
||||
|
||||
for overall code quality and static type checking. Both are very powerful tools and we depend on them a lot to prevent
|
||||
unforeseen bugs at "compile" time. Please make sure that your changes do NOT introduce new warnings. Fixing the old
|
||||
code that caused warnings are also much welcome.
|
||||
* **Type-annotate all function signatures (all arguments and return values).**
|
||||
|
||||
Testing and User Interface Design & User Experience
|
||||
===================================================
|
||||
As we lack both experience and contributors, we cannot even write contributions guidelines. =)
|
||||
|
||||
Just shoot us a message if you are interested in and let's discuss.
|
||||
|
||||
----
|
||||
|
||||
**P.S.** If you feel overwhelmed after seeing this document, don't. Send your first contributions and I'll personally
|
||||
help you through your first contribution. =)
|
||||
|
||||
Bora, <bora@boramalper.org>
|
Loading…
Reference in New Issue
Block a user