123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190 |
- .. _how to contribute:
- =================
- How to contribute
- =================
- .. contents:: Contents
- :depth: 2
- :local:
- :backlinks: entry
- Prime directives: Privacy, Hackability
- ======================================
- Searx has two prime directives, **privacy-by-design and hackability** . The
- hackability comes in three levels:
- - support of search engines
- - plugins to alter search behaviour
- - hacking searx itself
- Note the lack of "world domination" among the directives. Searx has no
- intention of wide mass-adoption, rounded corners, etc. The prime directive
- "privacy" deserves a separate chapter, as it's quite uncommon unfortunately.
- Privacy-by-design
- -----------------
- Searx was born out of the need for a **privacy-respecting** search tool which
- can be extended easily to maximize both, its search and its privacy protecting
- capabilities.
- A few widely used features work differently or turned off by default or not
- implemented at all **as a consequence of privacy-by-design**.
- If a feature reduces the privacy preserving aspects of searx, it should be
- switched off by default or should not implemented at all. There are plenty of
- search engines already providing such features. If a feature reduces the
- protection of searx, users must be informed about the effect of choosing to
- enable it. Features that protect privacy but differ from the expectations of
- the user should also be explained.
- Also, if you think that something works weird with searx, it's might be because
- of the tool you use is designed in a way to interfere with the privacy respect.
- Submitting a bugreport to the vendor of the tool that misbehaves might be a good
- feedback to reconsider the disrespect to its customers (e.g. ``GET`` vs ``POST``
- requests in various browsers).
- Remember the other prime directive of searx is to be hackable, so if the above
- privacy concerns do not fancy you, simply fork it.
- *Happy hacking.*
- Code
- ====
- .. _PEP8: https://www.python.org/dev/peps/pep-0008/
- .. _Conventional Commits: https://www.conventionalcommits.org/
- .. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages
- .. _Structural split of changes:
- https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes
- .. _gitmoji: https://gitmoji.carloscuesta.me/
- .. _Semantic PR: https://github.com/zeke/semantic-pull-requests
- .. sidebar:: Create good commits!
- - `Structural split of changes`_
- - `Conventional Commits`_
- - `Git Commit Good Practice`_
- - some like to use: gitmoji_
- - not yet active: `Semantic PR`_
- In order to submit a patch, please follow the steps below:
- - Follow coding conventions.
- - PEP8_ standards apply, except the convention of line length
- - Maximum line length is 120 characters
- - The cardinal rule for creating good commits is to ensure there is only one
- *logical change* per commit / read `Structural split of changes`_
- - Check if your code breaks existing tests. If so, update the tests or fix your
- code.
- - If your code can be unit-tested, add unit tests.
- - Add yourself to the :origin:`AUTHORS.rst` file.
- - Choose meaningful commit messages, read `Conventional Commits`_
- .. code::
- <type>[optional scope]: <description>
- [optional body]
- [optional footer(s)]
- - Create a pull request.
- For more help on getting started with searx development, see :ref:`devquickstart`.
- Translation
- ===========
- Translation currently takes place on :ref:`transifex <translation>`.
- .. caution::
- Please, do not update translation files in the repo.
- .. _contrib docs:
- Documentation
- =============
- .. _Sphinx: https://www.sphinx-doc.org
- .. _reST: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
- .. sidebar:: The reST sources
- has been moved from ``gh-branch`` into ``master`` (:origin:`docs`).
- The documentation is built using Sphinx_. So in order to be able to generate
- the required files, you have to install it on your system. Much easier, use
- our :ref:`makefile`.
- Here is an example which makes a complete rebuild:
- .. code:: sh
- $ make docs.clean docs.html
- ...
- The HTML pages are in dist/docs.
- .. _make docs.live:
- live build
- ----------
- .. _sphinx-autobuild:
- https://github.com/executablebooks/sphinx-autobuild/blob/master/README.md
- .. sidebar:: docs.clean
- It is recommended to assert a complete rebuild before deploying (use
- ``docs.clean``).
- Live build is like WYSIWYG. If you want to edit the documentation, its
- recommended to use. The Makefile target ``docs.live`` builds the docs, opens
- URL in your favorite browser and rebuilds every time a reST file has been
- changed.
- .. code:: sh
- $ make docs.live
- ...
- The HTML pages are in dist/docs.
- ... Serving on http://0.0.0.0:8000
- ... Start watching changes
- Live builds are implemented by sphinx-autobuild_. Use environment
- ``$(SPHINXOPTS)`` to pass arguments to the sphinx-autobuild_ command. Except
- option ``--host`` (which is always set to ``0.0.0.0``) you can pass any
- argument. E.g to find and use a free port, use:
- .. code:: sh
- $ SPHINXOPTS="--port 0" make docs.live
- ...
- ... Serving on http://0.0.0.0:50593
- ...
- .. _deploy on github.io:
- deploy on github.io
- -------------------
- To deploy documentation at :docs:`github.io <.>` use Makefile target :ref:`make
- docs.gh-pages`, which builds the documentation and runs all the needed git add,
- commit and push:
- .. code:: sh
- $ make docs.clean docs.gh-pages
|