git.iko.soy/searx
on f9be534 help sign in
searx/docs/dev/contribution_guide.rst
180 lines 5.3 kB history raw
1.. _how to contribute:
3=================
4How to contribute
5=================
7Prime directives: Privacy, Hackability
8======================================
10Searx has two prime directives, **privacy-by-design and hackability** . The
11hackability comes in three levels:
13- support of search engines
14- plugins to alter search behaviour
15- hacking searx itself
17Note the lack of "world domination" among the directives. Searx has no
18intention of wide mass-adoption, rounded corners, etc. The prime directive
19"privacy" deserves a separate chapter, as it's quite uncommon unfortunately.
21Privacy-by-design
22-----------------
24Searx was born out of the need for a **privacy-respecting** search tool which
25can be extended easily to maximize both, its search and its privacy protecting
26capabilities.
28A few widely used features work differently or turned off by default or not
29implemented at all **as a consequence of privacy-by-design**.
31If a feature reduces the privacy preserving aspects of searx, it should be
32switched off by default or should not implemented at all. There are plenty of
33search engines already providing such features. If a feature reduces the
34protection of searx, users must be informed about the effect of choosing to
35enable it. Features that protect privacy but differ from the expectations of
36the user should also be explained.
38Also, if you think that something works weird with searx, it's might be because
39of the tool you use is designed in a way to interfere with the privacy respect.
40Submitting a bugreport to the vendor of the tool that misbehaves might be a good
41feedback to reconsider the disrespect to its customers (e.g. ``GET`` vs ``POST``
42requests in various browsers).
44Remember the other prime directive of searx is to be hackable, so if the above
45privacy concerns do not fancy you, simply fork it.
47 *Happy hacking.*
49Code
50====
52.. _PEP8: https://www.python.org/dev/peps/pep-0008/
53.. _Conventional Commits: https://www.conventionalcommits.org/
54.. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages
55.. _Structural split of changes:
56 https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes
57.. _gitmoji: https://gitmoji.carloscuesta.me/
58.. _Semantic PR: https://github.com/zeke/semantic-pull-requests
60.. sidebar:: Create good commits!
62 - `Structural split of changes`_
63 - `Conventional Commits`_
64 - `Git Commit Good Practice`_
65 - some like to use: gitmoji_
66 - not yet active: `Semantic PR`_
68In order to submit a patch, please follow the steps below:
70- Follow coding conventions.
72 - PEP8_ standards apply, except the convention of line length
73 - Maximum line length is 120 characters
75- The cardinal rule for creating good commits is to ensure there is only one
76 *logical change* per commit / read `Structural split of changes`_
78- Check if your code breaks existing tests. If so, update the tests or fix your
79 code.
81- If your code can be unit-tested, add unit tests.
83- Add yourself to the :origin:`AUTHORS.rst` file.
85- Choose meaning full commit messages, read `Conventional Commits`_
87 .. code::
89 <type>[optional scope]: <description>
91 [optional body]
93 [optional footer(s)]
95- Create a pull request.
97For more help on getting started with searx development, see :ref:`devquickstart`.
100Translation
101===========
103Translation currently takes place on :ref:`transifex <translation>`.
105.. caution::
107 Please, do not update translation files in the repo.
110.. _contrib docs:
112Documentation
113=============
115.. _Sphinx: http://www.sphinx-doc.org
116.. _reST: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
118.. sidebar:: The reST sources
120 has been moved from ``gh-branch`` into ``master`` (:origin:`docs`).
122The documentation is built using Sphinx_. So in order to be able to generate
123the required files, you have to install it on your system. Much easier, use
124our :ref:`makefile`.
126Here is an example which makes a complete rebuild:
128.. code:: sh
130 $ make docs-clean docs
131 ...
132 The HTML pages are in dist/docs.
134.. _make docs-live:
136live build
137----------
139.. sidebar:: docs-clean
141 It is recommended to assert a complete rebuild before deploying (use
142 ``docs-clean``).
144Live build is like WYSIWYG. If you want to edit the documentation, its
145recommended to use. The Makefile target ``docs-live`` builds the docs, opens
146URL in your favorite browser and rebuilds every time a reST file has been
147changed.
149.. code:: sh
151 $ make docs-live
152 ...
153 The HTML pages are in dist/docs.
154 ... Serving on http://0.0.0.0:8080
155 ... Start watching changes
158.. _deploy on github.io:
160deploy on github.io
161-------------------
163To deploy documentation at :docs:`github.io <.>` use Makefile target
164:ref:`make gh-pages`, which will builds the documentation, clones searx into a sub
165folder ``gh-pages``, cleans it, copies the doc build into and runs all the
166needed git add, commit and push:
168.. code:: sh
170 $ make docs-clean gh-pages
171 ...
172 SPHINX docs --> file://<...>/dist/docs
173 The HTML pages are in dist/docs.
174 ...
175 Cloning into 'gh-pages' ...
176 ...
177 cd gh-pages; git checkout gh-pages >/dev/null
178 Switched to a new branch 'gh-pages'
179 ...
180 doc available at --> https://asciimoo.github.io/searx