Skip to content
Snippets Groups Projects
Commit 72763248 authored by vlorentz's avatar vlorentz
Browse files

Rename faq/faq.rst to faq/index.rst and deduplicate TOCs 

The FAQ was put in a single file in faq/faq.rst as a hack, using
multiple top-level headers in the same file to make them appear
in the global TOC.

With this change, the TOC is moved to the index.rst file, with
a single top-level header, and uses a local TOC instead, as it
should be.

Additionally, this removed the manually-written TOC in the main
index to use an auto-generated one.
parent 18d174df
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/faq/faq.rst deleted 100644 → 0
+ 0
− 247
View file @ 18d174df
.. _faq_prerequisites:
Prerequisites
=============
What are the Skills required to be a code contributor?
------------------------------------------------------
It depends on what area you want to work on. `Internships
<https://wiki.softwareheritage.org/wiki/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
<https://www.softwareheritage.org/community/developers/>`__ 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
<https://docs.softwareheritage.org/devel/developer-setup.html#developer-setup>`__ 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
<https://docs.softwareheritage.org/devel/index.html>`__ 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
<https://forge.softwareheritage.org/maniphest/query/WcCLxlHnXok9/>`__ to work on, see
the `Easy hacks page <https://wiki.softwareheritage.org/wiki/Easy_hacks>`__ 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
<https://wiki.softwareheritage.org/wiki/Internships>`__ to look for something matching
this skill, and this may allow you to find topics to search for in the `bug tracking
system <https://forge.softwareheritage.org/>`__.
Either way, feel free to `contact our developers
<https://www.softwareheritage.org/community/developers/>`__, we would love to work with
you.
Where should I ask for technical help?
--------------------------------------
You can choose one of the following:
* `development channels <https://www.softwareheritage.org/community/developers/>`__
* `contact form for any enquiries <https://www.softwareheritage.org/contact/>`__
.. _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
<https://docs.softwareheritage.org/devel/getting-started/using-docker.html#inserting-a-new-lister-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
<https://docs.softwareheritage.org/devel/swh-loader-core/package-loader-tutorial.html#with-docker>`__.
I have a SWH stack running in local, How do I setup a lister/loader job?
------------------------------------------------------------------------
See the `"Managing tasks" chapter
<https://docs.softwareheritage.org/devel/getting-started/using-docker.html#managing-tasks>`__
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 <https://docs.softwareheritage.org/devel/swh-dataset/index.html>`__. We can
also provide read access to one of the main databases on request `contact
us <https://www.softwareheritage.org/contact/>`__.
.. _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 <https://forge.softwareheritage.org/>`__.
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 <https://www.softwareheritage.org/community/developers/>`__ 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 <https://www.softwareheritage.org/community/developers/>`__, we will pick it up
and fix it so you don't have to follow the whole `code review
process <https://docs.softwareheritage.org/devel/contributing/phabricator.html>`__.
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 <https://docs.softwareheritage.org/devel/developer-setup.html#checkout-the-source-code>`__
and try again. If the error persists, you are welcome to drop us a message at one of the
`development channels <https://www.softwareheritage.org/community/developers/>`__
Is there a format/guideline for writing commit messages?
--------------------------------------------------------
See the `Git style guide <https://docs.softwareheritage.org/devel/contributing/git-style-guide.html>`__
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 <https://docs.softwareheritage.org/devel/swh-web-client/index.html#authentication>`__.
Is there a page where I can see all the API endpoints?
------------------------------------------------------
See the `API endpoint listing page <https://archive.softwareheritage.org/api/1/>`__.
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
<https://archive.softwareheritage.org/api/#rate-limiting>`__.
.. 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.
docs/faq/index.rst
+ 247
− 5
View file @ 72763248
.. _faq:
Frequently Asked Questions
==========================
**************************
.. toctree::
:maxdepth: 2
:titlesonly:
.. _faq_prerequisites:
Prerequisites for code contributions
====================================
What are the Skills required to be a code contributor?
------------------------------------------------------
It depends on what area you want to work on. `Internships
<https://wiki.softwareheritage.org/wiki/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
<https://www.softwareheritage.org/community/developers/>`__ 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
<https://docs.softwareheritage.org/devel/developer-setup.html#developer-setup>`__ 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
<https://docs.softwareheritage.org/devel/index.html>`__ 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
<https://forge.softwareheritage.org/maniphest/query/WcCLxlHnXok9/>`__ to work on, see
the `Easy hacks page <https://wiki.softwareheritage.org/wiki/Easy_hacks>`__ 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
<https://wiki.softwareheritage.org/wiki/Internships>`__ to look for something matching
this skill, and this may allow you to find topics to search for in the `bug tracking
system <https://forge.softwareheritage.org/>`__.
Either way, feel free to `contact our developers
<https://www.softwareheritage.org/community/developers/>`__, we would love to work with
you.
Where should I ask for technical help?
--------------------------------------
You can choose one of the following:
* `development channels <https://www.softwareheritage.org/community/developers/>`__
* `contact form for any enquiries <https://www.softwareheritage.org/contact/>`__
.. _faq_run_swh:
Running an 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
<https://docs.softwareheritage.org/devel/getting-started/using-docker.html#inserting-a-new-lister-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
<https://docs.softwareheritage.org/devel/swh-loader-core/package-loader-tutorial.html#with-docker>`__.
I have a SWH stack running in local, How do I setup a lister/loader job?
------------------------------------------------------------------------
See the `"Managing tasks" chapter
<https://docs.softwareheritage.org/devel/getting-started/using-docker.html#managing-tasks>`__
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:
Getting sample datasets
=======================
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 <https://docs.softwareheritage.org/devel/swh-dataset/index.html>`__. We can
also provide read access to one of the main databases on request `contact
us <https://www.softwareheritage.org/contact/>`__.
.. _faq_error_bugs:
Errors and bugs
===============
I found a bug/improvement in the system, where should I report it?
------------------------------------------------------------------
Please report it on our `bug tracking system <https://forge.softwareheritage.org/>`__.
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 <https://www.softwareheritage.org/community/developers/>`__ to
make sure we did not miss it.
.. _faq_legal:
Legal matters
=============
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 <https://www.softwareheritage.org/community/developers/>`__, we will pick it up
and fix it so you don't have to follow the whole `code review
process <https://docs.softwareheritage.org/devel/contributing/phabricator.html>`__.
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 <https://docs.softwareheritage.org/devel/developer-setup.html#checkout-the-source-code>`__
and try again. If the error persists, you are welcome to drop us a message at one of the
`development channels <https://www.softwareheritage.org/community/developers/>`__
Is there a format/guideline for writing commit messages?
--------------------------------------------------------
See the `Git style guide <https://docs.softwareheritage.org/devel/contributing/git-style-guide.html>`__
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:
Software Heritage API
=====================
How do I generate API usage credentials?
----------------------------------------
See the `Authentication guide <https://docs.softwareheritage.org/devel/swh-web-client/index.html#authentication>`__.
Is there a page where I can see all the API endpoints?
------------------------------------------------------
See the `API endpoint listing page <https://archive.softwareheritage.org/api/1/>`__.
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
<https://archive.softwareheritage.org/api/#rate-limiting>`__.
.. 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.
faq
docs/index.rst
+ 4
− 9
View file @ 72763248
......@@ -48,15 +48,10 @@ Tutorials
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
.. toctree::
:maxdepth: 2
faq/index
Roadmap
-------
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment