diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index d3122e9d8..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,49 +0,0 @@ -# How to contribute - -## Resources in the documentation - -* [Development quickstart](https://docs.searxng.org/dev/quickstart.html) -* [Contribution guide](https://docs.searxng.org/dev/contribution_guide.html) - -## Submitting PRs - -Please follow the provided PR template when writing a description for your changes. - -Do not take criticism personally. When you get feedback, it is about your work, -not your character, personality, etc. Keep in mind we all want to make the project better. - -When something is not clear, please ask questions to clear things up. - -If you would like to introduce a big architectural changes or do a refactoring -either in the codebase or the development tools, please open an issue with a proposal -first. This way we can think together about the problem and probably come up -with a better solution. - -## Coding conventions and guidelines - -### Commit messages - -* Always write descriptive commit messages ("fix bug" is not acceptable). -* Use the present tense ("Add feature" not "Added feature"). -* Use the imperative mood ("Move cursor to..." not "Moves cursor to..."). -* Limit the first line to 72 characters or less. -* Include the number of the issue you are fixing. - -### Coding guidelines - -As a Python project, we must follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) and [PEP 20](https://www.python.org/dev/peps/pep-0020/) guidelines. - -Furthermore, follow the Clean code conventions. The most important -in this project are the following rules: - -* Simpler is better. [KISS principle](https://en.wikipedia.org/wiki/KISS_principle) -* Be consistent. -* Every function must do one thing. -* Use descriptive names for functions and variables. -* Always look for the root cause. -* Keep configurable data high level. -* Avoid negative conditionals. -* Prefer fewer arguments. -* Do not add obvious comment to code. -* Do not comment out code, just delete lines. - diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..b0a81f70c --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: AGPL-3.0-or-later + +.. _Quickstart guide: https://docs.searxng.org/dev/quickstart.html +.. _Commits guide: https://docs.searxng.org/dev/commits.html +.. _Weblate: https://translate.codeberg.org/projects/searxng/searxng/ +.. _GitHub Codespaces: https://docs.github.com/en/codespaces/overview +.. _120 hours per month: https://github.com/settings/billing +.. _list of existing Codespaces: https://github.com/codespaces + +Thank you for your interest in SearXNG. + +Have a look at our `Quickstart guide`_, it's very easy to contribute. + +Further information on *how-to* can be found +`here `_. + +Translations +============ + +Help translate SearXNG at `Weblate`_. + +.. image:: https://translate.codeberg.org/widget/searxng/searxng/horizontal-auto.svg + :target: https://translate.codeberg.org/engage/searxng/ + :alt: Weblate + :width: 768px + +Cloud development +================= + +You can contribute from your browser using `GitHub Codespaces`_: + +- Fork the repository. +- Click on the ``<> Code`` green button. +- Click on the ``Codespaces`` tab instead of ``Local``. +- Click on ``Create codespace on master``. +- VSCode is going to start in the browser. +- Wait for ``git pull && make install`` to appear and then disappear. +- You have `120 hours per month`_ (see also your `list of existing Codespaces`_). +- You can start SearXNG using ``make run`` in the terminal or by pressing ``Ctrl+Shift+B``. + +How-to contribute +================= + +Submitting pull requests +------------------------ + +Please follow the provided PR template when writing a description for your +changes. + +Do not take criticism personally. When you get feedback, it is about your work, +not your character or personality. Keep in mind we all want to make SearXNG +better. + +When something is not clear, please ask questions to clear things up. + +If you would like to introduce a big architectural change or do a refactor, +either in the codebase or the development tooling, please open an issue with a +proposal first. This way we can think together about the problem and probably +come up with a better solution. + +Coding conventions and guidelines +--------------------------------- + +Commit messages +~~~~~~~~~~~~~~~ + +- Always write descriptive commit messages *("fix bug" is not acceptable)*. +- Use the present tense *("Add feature", not "Added feature")*. +- Use the imperative mood *("Move cursor to...", not "Moves cursor to...")*. +- Limit the first line (commit title) to 72 characters or less. + +See `Commits guide`_ for more details. + +Coding guidelines +~~~~~~~~~~~~~~~~~ + +As a Python project, we must follow `PEP 8 `_ +and `PEP 20 `_ guidelines. + +Furthermore, follow Clean Code conventions. The most important +rules in this project are: + +- Simpler is better. `KISS principle `_ +- Be consistent. +- Every function must do one thing. +- Use descriptive names for functions and variables. +- Always look for the root cause. +- Keep configurable data high level. +- Avoid negative conditionals. +- Prefer fewer arguments. +- Do not add obvious comments to code. +- Do not comment out code, delete lines instead. diff --git a/README.rst b/README.rst index 20c9175bb..15c136879 100644 --- a/README.rst +++ b/README.rst @@ -1,130 +1,65 @@ .. SPDX-License-Identifier: AGPL-3.0-or-later ----- +.. _metasearch engine: https://en.wikipedia.org/wiki/Metasearch_engine +.. _Installation guide: https://docs.searxng.org/admin/installation.html +.. _Configuration guide: https://docs.searxng.org/admin/settings/index.html +.. _CONTRIBUTING: https://raw.githubusercontent.com/searxng/searxng/refs/heads/master/CONTRIBUTING.rst +.. _LICENSE: https://raw.githubusercontent.com/searxng/searxng/refs/heads/master/LICENSE .. figure:: https://raw.githubusercontent.com/searxng/searxng/master/client/simple/src/brand/searxng.svg - :target: https://docs.searxng.org/ + :target: https://searxng.org :alt: SearXNG - :width: 100% - :align: center + :width: 512px ----- +| -Privacy-respecting, hackable `metasearch engine`_ +SearXNG is a `metasearch engine`_. Users are neither tracked nor profiled. -Searx.space_ lists ready-to-use running instances. +.. image:: https://img.shields.io/badge/organization-3050ff?style=flat-square&logo=searxng&logoColor=fff&cacheSeconds=86400 + :target: https://github.com/searxng + :alt: Organization -A user_, admin_ and developer_ handbook is available on the homepage_. +.. image:: https://img.shields.io/badge/documentation-3050ff?style=flat-square&logo=readthedocs&logoColor=fff&cacheSeconds=86400 + :target: https://docs.searxng.org + :alt: Documentation -|SearXNG install| -|SearXNG homepage| -|SearXNG wiki| -|AGPL License| -|Issues| -|commits| -|weblate| -|SearXNG logo| +.. image:: https://img.shields.io/github/license/searxng/searxng?style=flat-square&label=license&color=3050ff&cacheSeconds=86400 + :target: https://raw.githubusercontent.com/searxng/searxng/refs/heads/master/LICENSE + :alt: License ----- +.. image:: https://img.shields.io/github/commit-activity/y/searxng/searxng/master?style=flat-square&label=commits&color=3050ff&cacheSeconds=3600 + :target: https://github.com/searxng/searxng/commits/master/ + :alt: Commits -.. _searx.space: https://searx.space -.. _user: https://docs.searxng.org/user -.. _admin: https://docs.searxng.org/admin -.. _developer: https://docs.searxng.org/dev -.. _homepage: https://docs.searxng.org/ -.. _metasearch engine: https://en.wikipedia.org/wiki/Metasearch_engine - -.. |SearXNG logo| image:: https://raw.githubusercontent.com/searxng/searxng/master/client/simple/src/brand/searxng-wordmark.svg - :target: https://docs.searxng.org/ - :width: 5% - -.. |SearXNG install| image:: https://img.shields.io/badge/-install-blue - :target: https://docs.searxng.org/admin/installation.html - -.. |SearXNG homepage| image:: https://img.shields.io/badge/-homepage-blue - :target: https://docs.searxng.org/ - -.. |SearXNG wiki| image:: https://img.shields.io/badge/-wiki-blue - :target: https://github.com/searxng/searxng/wiki - -.. |AGPL License| image:: https://img.shields.io/badge/license-AGPL-blue.svg - :target: https://github.com/searxng/searxng/blob/master/LICENSE - -.. |Issues| image:: https://img.shields.io/github/issues/searxng/searxng?color=yellow&label=issues - :target: https://github.com/searxng/searxng/issues - -.. |PR| image:: https://img.shields.io/github/issues-pr-raw/searxng/searxng?color=yellow&label=PR - :target: https://github.com/searxng/searxng/pulls - -.. |commits| image:: https://img.shields.io/github/commit-activity/y/searxng/searxng?color=yellow&label=commits - :target: https://github.com/searxng/searxng/commits/master - -.. |weblate| image:: https://translate.codeberg.org/widgets/searxng/-/searxng/svg-badge.svg +.. image:: https://img.shields.io/weblate/progress/searxng?server=https%3A%2F%2Ftranslate.codeberg.org&style=flat-square&label=translated&color=3050ff&cacheSeconds=86400 :target: https://translate.codeberg.org/projects/searxng/ - - -Contact -======= - -Ask questions or chat with the SearXNG community (this not a chatbot) on - -IRC - `#searxng on libera.chat `_ - which is bridged to Matrix. - -Matrix - `#searxng:matrix.org `_ - + :alt: Translated Setup ===== -- A well maintained `Docker image`_, also built for ARM64 and ARM/v7 - architectures. -- Alternatively there are *up to date* `installation scripts`_. -- For individual setup consult our detailed `Step by step`_ instructions. -- To fine-tune your instance, take a look at the `Administrator documentation`_. +To install SearXNG, see `Installation guide`_. -.. _Administrator documentation: https://docs.searxng.org/admin/index.html -.. _Step by step: https://docs.searxng.org/admin/installation-searxng.html -.. _installation scripts: https://docs.searxng.org/admin/installation-scripts.html -.. _Docker image: https://github.com/searxng/searxng-docker +To fine-tune SearXNG, see `Configuration guide`_. -Translations -============ +Further information on *how-to* can be found `here `_. -.. _Weblate: https://translate.codeberg.org/projects/searxng/searxng/ +Connect +======= -Help translate SearXNG at `Weblate`_ - -.. figure:: https://translate.codeberg.org/widgets/searxng/-/multi-auto.svg - :target: https://translate.codeberg.org/projects/searxng/ +If you have questions or want to connect with others in the community, +we have two official channels: +- `#searxng:matrix.org `_ +- `#searxng @ libera.chat `_ (bridged to Matrix) Contributing ============ -.. _development quickstart: https://docs.searxng.org/dev/quickstart.html -.. _developer documentation: https://docs.searxng.org/dev/index.html +See `CONTRIBUTING`_ for more details. -Are you a developer? Have a look at our `development quickstart`_ guide, it's -very easy to contribute. Additionally we have a `developer documentation`_. +License +======= - -Codespaces -========== - -You can contribute from your browser using `GitHub Codespaces`_: - -- Fork the repository -- Click on the ``<> Code`` green button -- Click on the ``Codespaces`` tab instead of ``Local`` -- Click on ``Create codespace on master`` -- VSCode is going to start in the browser -- Wait for ``git pull && make install`` to appear and then disappear -- You have `120 hours per month`_ (see also your `list of existing Codespaces`_) -- You can start SearXNG using ``make run`` in the terminal or by pressing ``Ctrl+Shift+B`` - -.. _GitHub Codespaces: https://docs.github.com/en/codespaces/overview -.. _120 hours per month: https://github.com/settings/billing -.. _list of existing Codespaces: https://github.com/codespaces +This project is licensed under the GNU Affero General Public License (AGPL-3.0). +See `LICENSE`_ for more details.