diff --git a/docs/faq.rst b/docs/faq.rst deleted file mode 100644 --- a/docs/faq.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _faq: - -Frequently Asked Questions -========================== - -How can I compute my SWHID? ---------------------------- - -We propose a cli to ease such computation ``swh identify``... - -how should I document the code I contribute to SWH? ---------------------------------------------------- - -Any new feature should include documentation in the form of comments and/or docstrings. -Ideally, they should also be documented in plain English in the repository's `docs/` -folder if relevant to a single package, or in the main `swh-docs` repository if it is a -transversal feature. - -What are the minimum system requirements (hardware/software) to run SWH locally? --------------------------------------------------------------------------------- - -See the `developer setup documentation `__ - diff --git a/docs/faq/faq.rst b/docs/faq/faq.rst new file mode 100644 --- /dev/null +++ b/docs/faq/faq.rst @@ -0,0 +1,247 @@ +.. _faq_prerequisites: + +Prerequisites +============= + +What are the Skills required to be a code contributor? +------------------------------------------------------ + +It depends on what area you want to work on. `Internships +`__ postings list specific skills +required. Generally, only Python and basic Git knowledge are required. Feel free to +contact us on one of the `development channels +`__ for details. + +What are the minimum system requirements (hardware/software) to run SWH locally? +-------------------------------------------------------------------------------- + +Python3.7 or newer is required. See the `developer setup documentation +`__ for +more details. + + +.. _faq_getting_started: + +Getting Started +================ + +What are the must read docs before I start contributing? +-------------------------------------------------------- + +We recommend you read the top links listed at from the `documentation home page +`__ in order: getting started, +contributing, and architecture, as well as the data model. + +Where can I see the getting started guide for developers? +--------------------------------------------------------- + +See :ref:`getting-started` tutorial. + +How do I find an easy ticket to get started? +-------------------------------------------- + +We maintain a `list of easy tickets +`__ to work on, see +the `Easy hacks page `__ for more +details. + +I am skilled in one specific technology, can I find tickets requiring that skill? +--------------------------------------------------------------------------------- + +Unfortunately, not at the moment. But you can look at the `Internship list +`__ to look for something matching +this skill, and this may allow you to find topics to search for in the `bug tracking +system `__. + +Either way, feel free to `contact our developers +`__, we would love to work with +you. + +Where should I ask for technical help? +-------------------------------------- + +You can choose one of the following: + +* `development channels `__ +* `contact form for any enquiries `__ + +.. _faq_run_swh: + +Running SWH instance locally +============================ + +I have SWH stack running in my local. How do I get some initial data to play around? +------------------------------------------------------------------------------------ + +You can setup a job on your local machine, for this you can `schedule a listing task +`__ +for example. Doing so on small forge, will allow you to load some repositories. + +Or you can also trigger directly `loading from the cli +`__. + +I have a SWH stack running in local, How do I setup a lister/loader job? +------------------------------------------------------------------------ + +See the `"Managing tasks" chapter +`__ +in the Docker environment documentation. + +How can I create a user in my local instance? +--------------------------------------------- + +We cannot right now. Stay either anonymous or use the user "test" (password "test") or +the user ambassador (password "ambassador"). + +Should I run/test the web app in any particular browser? +-------------------------------------------------------- + +We expect the web app to work on all major browsers. It uses mostly straightforward +HTML/CSS and a little Javascript for search and source code highlighting, so testing in +a single browser is usually enough. + +.. _faq_dataset: + +Dataset +======= + +Is there a way to connect to SWH archived (production) database from my local machine? +-------------------------------------------------------------------------------------- + +We provide the archive as a dataset on public clouds, see the `swh-dataset +documentation `__. We can +also provide read access to one of the main databases on request `contact +us `__. + +.. _faq_error_bugs: + +Error and bugs +============== + +I found a bug/improvement in the system, where should I report it? +------------------------------------------------------------------ + +Please report it on our `bug tracking system `__. +First create an account, then create a bug report using the "Create task" button. You +should get some feedback within a week (at least someone triaging your issue). If not, +`get in touch with us `__ to +make sure we did not miss it. + +.. _faq_legal: + +Legal +===== + +Do I need to sign a form to contribute code? +-------------------------------------------- + +Yes, on your first diff, you will have to sign such document. +As long as it's not signed, your diff content won't be visible. + +Will my name be added to a CONTRIBUTORS file? +--------------------------------------------- + +You will be asked during review to add yourself. + +.. _faq_code_review: + +Code Review +=========== + +I found a straightforward typo fix, should my fix go through the entire code review process? +-------------------------------------------------------------------------------------------- + +You are welcome to drop us a message at one of the `development +channels `__, we will pick it up +and fix it so you don't have to follow the whole `code review +process `__. + +What tests I should run before committing the code? +--------------------------------------------------- + +Mostly run `tox` (or `pytest`) to run the unit tests suite. When you will propose a +patch in our forge, the continuous integration factory will trigger a build (using `tox` +as well). + +I am getting errors while trying to commit. What is going wrong? +---------------------------------------------------------------- + +Ensure you followed the proper guide to `setup your +environment `__ +and try again. If the error persists, you are welcome to drop us a message at one of the +`development channels `__ + +Is there a format/guideline for writing commit messages? +-------------------------------------------------------- + +See the `Git style guide `__ + +Is there some recommended git branching strategy? +------------------------------------------------- + +It's left at the developer's discretion. Mostly people hack on their feature, then +propose a diff from a git branch or directly from the master branch. There is no +imperative. The only imperative is that for a feature to be packaged and deployed, it +needs to land first in the master branch. + +how should I document the code I contribute to SWH? +--------------------------------------------------- + +Any new feature should include documentation in the form of comments and/or docstrings. +Ideally, they should also be documented in plain English in the repository's `docs/` +folder if relevant to a single package, or in the main `swh-docs` repository if it is a +transversal feature. + +.. _faq_api: + +API +=== + +How do I generate API usage credentials? +---------------------------------------- + +See the `Authentication guide `__. + +Is there a page where I can see all the API endpoints? +------------------------------------------------------ + +See the `API endpoint listing page `__. + +What are the usage limits for SWH APIs? +--------------------------------------- + +Maximum number of permitted requests per hour: + +* 120 for anonymous users +* 1200 for authenticated users + +It's described in the `rate limit documentation page +`__. + +.. It's temporarily here but it should be moved into its own sphinx instance at some + point in the future. + +.. _faq_sysadm: + +System Administration +===================== + +How does SWH release? +--------------------- + +Release is mostly done: +- first in docker (somewhat as part of the development process) +- secondly packaged and deployed on staging (mostly) +- thirdly the same package is deployed on production + +Is there a release cycle? +------------------------- + +When a functionality is ready (tests ok, landed in master, docker run ok), the module is +tagged. The tag is pushed. This triggers a packaging build process. When the package is +ready, depending on the module [1], sysadms deploy the package with the help of puppet. + +[1] swh-web module is mostly automatic. Other modules are not yet automatic as some +internal state migration (dbs) often enters the release cycle and due to the data +volume, that may need human intervention. + diff --git a/docs/faq/index.rst b/docs/faq/index.rst new file mode 100644 --- /dev/null +++ b/docs/faq/index.rst @@ -0,0 +1,11 @@ +.. _faq: + +Frequently Asked Questions +========================== + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + faq + diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -44,8 +44,19 @@ * :doc:`/tutorials/issue-debugging-monitoring` * :ref:`Listing the content of your favorite forge ` and :ref:`running a lister in Docker ` -* :ref:`faq` +Frequently Asked Questions +-------------------------- + +* :ref:`faq_prerequisites` Prerequisites to be a contributor +* :ref:`faq_getting_started` Starter kit to contribute +* :ref:`faq_run_swh` Starter kit to run your local swh instance +* :ref:`faq_dataset` Getting some sample dataset +* :ref:`faq_error_bugs` Stuck somewhere +* :ref:`faq_legal` Legal and contributions +* :ref:`faq_code_review` Related to Code review +* :ref:`faq_api` General questions about the SWH API +* :ref:`faq_sysadm` System Administration related questions Roadmap ------- @@ -200,7 +211,7 @@ architecture/index contributing/index tutorials/index - faq + faq/index roadmap/roadmap-2021.rst infrastructure/index swh.auth