contribute.rst 4.95 KB
Newer Older
1 2 3
==================
Contribution Guide
==================
Ali Rıza's avatar
Ali Rıza committed
4

5 6 7 8 9 10 11 12
.. toctree::
   :maxdepth: 2
   :caption: Contribution Guide
   :hidden:
   :includehidden:

   Contributors <contributors>

Ali Rıza's avatar
Ali Rıza committed
13 14
What can I do?
--------------
15 16
Since Beiran is a free software and follows the free software
development conventions and patterns, it is open for any kind
17 18 19 20 21 22 23 24 25 26 27 28 29 30
of contribution. So you can:

- report a bug,
- make a feature request to enhance / improve Beiran,
- create a merge request if you implemented or fixed something,
- start a technical discussion,
- start a plugin project,
- join discussions on our developer email list.

The primary channel for technical issues is our issue tracker. Please
create an issue to report a bug, make a feature request or start any kind
of technical discussions. You can access Issue Dashboard by visiting
address below:

31
`Issue Tracker`_
32

33
You need to create an account on our GitLab_ instance. It's easy. Click
34 35 36
**Sign in / Register** button. Fill the registration form. Approve your
email address. That's it.

37 38 39 40
You can join our email list to follow and join design and implementation
discussions. You can ask your questions to get help. Please subscribe it
by sending an email to:

41
|email_list_subscribe_link|
42 43 44

Where is the source code?
-------------------------
45
Here it is: |repo_url|. Please fork it and start coding!
46

Furkan Mustafa's avatar
Furkan Mustafa committed
47
We accept code contributions via Merge Requests. Simply you should do:
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63

- fork project
- change the code (on default branch or a new branch if necessary)
- click `create merge request` button
- fill the required information on the following screen
- submit your changes

and that's it.

**What information we expect** in a merge request?

- A short and descriptive title
- A detailed explanation containing
    - which issues does it fix or close (if there exist)
    - how does it solve problems
- Related labels, bug / feature / security / urgent etc.
Ali Rıza's avatar
Ali Rıza committed
64

65

Ali Rıza's avatar
Ali Rıza committed
66 67
How to code
-----------
68 69
Beiran is written in Python. We follow some general coding conventions which
is known and used widely in Python communities.
70

71
pep8
72
    Please follow pep8 rules. See here: https://www.python.org/dev/peps/pep-0008/
73

74 75 76 77 78
documentation
    We use sphinx to generate documentation. Do not forget inline docstrings.
    They compose the main part of our documentation. Please visit this page
    to learn how to write docstrings:
    http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
79

80 81
    Or browse the samples through current source code.

82 83 84
pylint
    check your code with **pylint** using our `.pylintrc` configuration
    file which can be found in root folder of project.
85

86 87 88 89 90 91 92 93
    All you need to do is run `pylint` and check the console output for results::

        $ pylint beiran/

        -------------------------------------------------------------------
        Your code has been rated at 10.00/10 (previous run: 8.88/10, +1.12)


94 95 96 97 98 99 100
requirements
    if you use a new 3rd party library, please do not forget adding
    it to `requirement.txt` files.

type hinting
    please add type hints to your objects as much as possible in
    general, it is a must for those which are supposed to be used
101
    by other objects or the ones in lib modules.
102

103
    please run `mypy` for type checking, there is a configuration file
104 105 106
    named `mypy.ini` in root folder::

        $ mypy beiran/
107

108
    The command above gives no output if there is nothing wrong.
109

110

111
Git Workflow
112 113 114
------------
Please create a topic branch using an explicit name including issue number::

115
    $ git checkout -b 258-build-docs-using-gitlab-ci
116 117 118 119 120 121 122 123

Change the code and commit them with a message explaining enough::

    $ git add docs/source/contribute.rst
    $ git add ..   # other changes
    $ git commit -S -m 'documentation, adds new page, how to create plugin'
    $ git push -u origin 258-build-docs-using-gitlab-ci

124 125 126 127
Sign Your Commits
-----------------
Signed commits add an extra security and trust layer to git environment.
It proves cryptographically the owner of the work.
128

129 130
If you haven't done already, please configure your git client to sign
your commits.
131

132
You can find detailed guide here:
133 134 135

https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work

136 137
After configuring git client, add your **public key** of your gpg pair
to your gitlab profile.
138 139

See here for more details:
140 141

https://docs.gitlab.com/ce/user/project/repository/gpg_signed_commits/
142

143
.. warning:: Also please `--signoff` one of your commits to declare
144
 approving DCO. Please see and read carefully **Copyright** and **DCO** section below.
145

146 147 148
Copyright
---------
Along with whole Beiran source code, all your contributions are licenced
149
under **GPL v3** which allows anybody to copy, change, distribute or redistribute it.
150 151
By sending your source code or any kind of contributions you also accept the
licence's terms and conditions.
152

153
DCO
154 155
---
Contributors' work is protected with **Developer Certificate of Origin** which
156
can be found project root dir in `DCO` file or here https://developercertificate.org/
157

158 159
**By contributing this project you agree with `DCO` and certify your contribution as
described in `DCO`.**