Page MenuHomeSoftware Heritage
Files F9342126

D5922.diff
No OneTemporary
Actions

D5922.diff
View Options

diff --git a/docs/faq/faq.rst b/docs/faq/faq.rst
deleted file mode 100644
--- a/docs/faq/faq.rst
+++ /dev/null
@@ -1,247 +0,0 @@
-.. _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.
-
diff --git a/docs/faq/index.rst b/docs/faq/index.rst
--- a/docs/faq/index.rst
+++ b/docs/faq/index.rst
@@ -1,10 +1,252 @@
.. _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
diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -48,15 +48,10 @@
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
-------

File Metadata

Mime Type
text/plain
Expires
Thu, Jul 3, 12:30 PM (2 w, 4 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
3218582

Event Timeline

About · Developer information · Legal