magnetico/CONTRIBUTING.rst
Gary Coulbourne 4250c47537
Python -> Go
Since the software was ported to Go, edited the contribution details to reflect this.
2019-10-03 09:40:44 -04:00

91 lines
4.8 KiB
ReStructuredText

=========================
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 **Go** programmer, great! **JavaScript** programmers are too welcome. **magneticod** and
**magneticow** are programmed in Go, 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. Go is compiled, and the native encoding is UTF-8, for every and each source file.
* Prefer Go 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>