git.iko.soy/searx
on master help sign in
searx/docs/dev/contribution_guide.rst
189 lines 5.5 kB history raw
1.. _how to contribute:
3=================
4How to contribute
5=================
7.. contents:: Contents
8 :depth: 2
9 :local:
10 :backlinks: entry
12Prime directives: Privacy, Hackability
13======================================
15Searx has two prime directives, **privacy-by-design and hackability** . The
16hackability comes in three levels:
18- support of search engines
19- plugins to alter search behaviour
20- hacking searx itself
22Note the lack of "world domination" among the directives. Searx has no
23intention of wide mass-adoption, rounded corners, etc. The prime directive
24"privacy" deserves a separate chapter, as it's quite uncommon unfortunately.
26Privacy-by-design
27-----------------
29Searx was born out of the need for a **privacy-respecting** search tool which
30can be extended easily to maximize both, its search and its privacy protecting
31capabilities.
33A few widely used features work differently or turned off by default or not
34implemented at all **as a consequence of privacy-by-design**.
36If a feature reduces the privacy preserving aspects of searx, it should be
37switched off by default or should not implemented at all. There are plenty of
38search engines already providing such features. If a feature reduces the
39protection of searx, users must be informed about the effect of choosing to
40enable it. Features that protect privacy but differ from the expectations of
41the user should also be explained.
43Also, if you think that something works weird with searx, it's might be because
44of the tool you use is designed in a way to interfere with the privacy respect.
45Submitting a bugreport to the vendor of the tool that misbehaves might be a good
46feedback to reconsider the disrespect to its customers (e.g. ``GET`` vs ``POST``
47requests in various browsers).
49Remember the other prime directive of searx is to be hackable, so if the above
50privacy concerns do not fancy you, simply fork it.
52 *Happy hacking.*
54Code
55====
57.. _PEP8: https://www.python.org/dev/peps/pep-0008/
58.. _Conventional Commits: https://www.conventionalcommits.org/
59.. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages
60.. _Structural split of changes:
61 https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes
62.. _gitmoji: https://gitmoji.carloscuesta.me/
63.. _Semantic PR: https://github.com/zeke/semantic-pull-requests
65.. sidebar:: Create good commits!
67 - `Structural split of changes`_
68 - `Conventional Commits`_
69 - `Git Commit Good Practice`_
70 - some like to use: gitmoji_
71 - not yet active: `Semantic PR`_
73In order to submit a patch, please follow the steps below:
75- Follow coding conventions.
77 - PEP8_ standards apply, except the convention of line length
78 - Maximum line length is 120 characters
80- The cardinal rule for creating good commits is to ensure there is only one
81 *logical change* per commit / read `Structural split of changes`_
83- Check if your code breaks existing tests. If so, update the tests or fix your
84 code.
86- If your code can be unit-tested, add unit tests.
88- Add yourself to the :origin:`AUTHORS.rst` file.
90- Choose meaningful commit messages, read `Conventional Commits`_
92 .. code::
94 <type>[optional scope]: <description>
96 [optional body]
98 [optional footer(s)]
100- Create a pull request.
102For more help on getting started with searx development, see :ref:`devquickstart`.
105Translation
106===========
108Translation currently takes place on :ref:`transifex <translation>`.
110.. caution::
112 Please, do not update translation files in the repo.
115.. _contrib docs:
117Documentation
118=============
120.. _Sphinx: https://www.sphinx-doc.org
121.. _reST: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
123.. sidebar:: The reST sources
125 has been moved from ``gh-branch`` into ``master`` (:origin:`docs`).
127The documentation is built using Sphinx_. So in order to be able to generate
128the required files, you have to install it on your system. Much easier, use
129our :ref:`makefile`.
131Here is an example which makes a complete rebuild:
133.. code:: sh
135 $ make docs.clean docs.html
136 ...
137 The HTML pages are in dist/docs.
139.. _make docs.live:
141live build
142----------
144.. _sphinx-autobuild:
145 https://github.com/executablebooks/sphinx-autobuild/blob/master/README.md
147.. sidebar:: docs.clean
149 It is recommended to assert a complete rebuild before deploying (use
150 ``docs.clean``).
152Live build is like WYSIWYG. If you want to edit the documentation, its
153recommended to use. The Makefile target ``docs.live`` builds the docs, opens
154URL in your favorite browser and rebuilds every time a reST file has been
155changed.
157.. code:: sh
159 $ make docs.live
160 ...
161 The HTML pages are in dist/docs.
162 ... Serving on http://0.0.0.0:8000
163 ... Start watching changes
165Live builds are implemented by sphinx-autobuild_. Use environment
166``$(SPHINXOPTS)`` to pass arguments to the sphinx-autobuild_ command. Except
167option ``--host`` (which is always set to ``0.0.0.0``) you can pass any
168argument. E.g to find and use a free port, use:
170.. code:: sh
172 $ SPHINXOPTS="--port 0" make docs.live
173 ...
174 ... Serving on http://0.0.0.0:50593
175 ...
178.. _deploy on github.io:
180deploy on github.io
181-------------------
183To deploy documentation at :docs:`github.io <.>` use Makefile target :ref:`make
184docs.gh-pages`, which builds the documentation and runs all the needed git add,
185commit and push:
187.. code:: sh
189 $ make docs.clean docs.gh-pages