Changeset View
Changeset View
Standalone View
Standalone View
docs/tutorials/add-a-new-module.rst
- This file was added.
.. _add-a-new-module: | |||||||||||||||||||
vlorentz: I try to avoid stop words in anchor names. What about `.. _tutorial-new-package:`? | |||||||||||||||||||
Done Inline ActionsSure. Note that i think it's an how to though (see diff description) but fine. ardumont: Sure.
Note that i think it's an how to though (see diff description) but fine. | |||||||||||||||||||
Add a new module | |||||||||||||||||||
================ | |||||||||||||||||||
The following tutorial demonstrates how to create a new swh module in the current swh | |||||||||||||||||||
phabricator instance and reference it so the Continuous Integration (CI) is able to | |||||||||||||||||||
build the new module. | |||||||||||||||||||
We will need to (optionally) create a project, then create a repository, reference it in | |||||||||||||||||||
the CI and finally update the documentation repository so the docs get built with that | |||||||||||||||||||
new module. Optionally, we can also create the necessary debian branches for the debian | |||||||||||||||||||
build deployment process to work. That's not something immediately urgent when | |||||||||||||||||||
bootstraping a module though. | |||||||||||||||||||
Create a project | |||||||||||||||||||
---------------- | |||||||||||||||||||
Create a `new project/tag <https://forge.softwareheritage.org/project/edit/form/3/>`__ | |||||||||||||||||||
and fill in the form: | |||||||||||||||||||
- Fill in the "name" field (e.g. ``Origin Sourceforge``, ``Loader XYZ``, ...) | |||||||||||||||||||
- Additional hashtags should be filled in with easy to remember hashstags (e.g. ``#sourceforge``, ``#loader-xyz``) | |||||||||||||||||||
Done Inline Actions
vlorentz: | |||||||||||||||||||
- Add a small description about what the project is about | |||||||||||||||||||
Create a repository | |||||||||||||||||||
------------------- | |||||||||||||||||||
- Create a `new Git repository <https://forge.softwareheritage.org/diffusion/edit/form/default/?vcs=git>`__ and fill in the form: | |||||||||||||||||||
- ``name`` of the repository should be human readable (e.g. ``Loader Git``, ``Lister Gitlab``) | |||||||||||||||||||
Done Inline Actions
vlorentz: | |||||||||||||||||||
- ``callsign`` should follow `the current naming convention <https://wiki.softwareheritage.org/wiki/Phabricator_callsign_naming_convention>`__ | |||||||||||||||||||
- ``short-name`` should be lower case and dash separated (e.g. swh-loader-git, swh-lister, ...) | |||||||||||||||||||
- ``Tags`` should be filled with the project/tag you created in the `optional first step <#create-a-project>`__ | |||||||||||||||||||
- Add tags in the ``Tags`` form: | |||||||||||||||||||
Done Inline ActionsDefine an anchor for Create a project and use a :ref: to point to it. Written this way, it depends on how the HTML renderer auto-generates anchors, which is somewhat brittle. (And also HTML-specific) vlorentz: Define an anchor for `Create a project` and use a `:ref:` to point to it.
Written this way, it… | |||||||||||||||||||
- ``Language-Python``: Enable unit test on commit | |||||||||||||||||||
- ``Has debian packaging branches``: Activate? debian builds | |||||||||||||||||||
- ``Sync to github``: Activate sync to github | |||||||||||||||||||
Done Inline ActionsThis should probably explain when they should be enabled vlorentz: This should probably explain when they should be enabled | |||||||||||||||||||
Done Inline Actionsyes, i did not enter much into it because 1. i don't remember what needs to be done after that 2. and i think that'd need a dedicated doc... ardumont: yes, i did not enter much into it because 1. i don't remember what needs to be done after that… | |||||||||||||||||||
- Add the staging area, click in order from ``BUILDS`` (left menu) > ``Staging Area`` > | |||||||||||||||||||
``Edit staging`` > fill in ``Staging Area URI`` with | |||||||||||||||||||
https://forge.softwareheritage.org/source/staging.git | |||||||||||||||||||
- Finally, activate the repository | |||||||||||||||||||
Add the repo on the swh-environment project | |||||||||||||||||||
------------------------------------------- | |||||||||||||||||||
(Only if necessary) | |||||||||||||||||||
- clone the new repository on the base directory | |||||||||||||||||||
.. code:: bash | |||||||||||||||||||
git clone ssh://git@forge.softwareheritage.org/source/swh-my-new-repo.git | |||||||||||||||||||
- launch the command ``bin/init-py-repo`` to initialize the repository with a project | |||||||||||||||||||
template | |||||||||||||||||||
.. code:: bash | |||||||||||||||||||
bin/init-py-repo swh-new-repo | |||||||||||||||||||
- Edit the default content of the template (`Example <https://forge.softwareheritage.org/rDCNT142fff84305b793974e6f7b837988e5fb95d8db1>`__) | |||||||||||||||||||
- Configure **your local** pre-commit hook | |||||||||||||||||||
- In the ``swh-environment/swh-my-new-repo`` directory, execute: | |||||||||||||||||||
.. code:: bash | |||||||||||||||||||
grep -q pre-commit.com .git/hooks/pre-commit || pre-commit install | |||||||||||||||||||
- Declare the repository on the mr configuration | |||||||||||||||||||
- Edit the ``swh-environment/.mrconfig`` file and declare the new repository as the | |||||||||||||||||||
others | |||||||||||||||||||
- Commit file modifications (`Example <https://forge.softwareheritage.org/rCJSWHede4a65bc9e103db99dd8b0690caa3a769b378bd>`__) | |||||||||||||||||||
Install CI jobs | |||||||||||||||||||
--------------- | |||||||||||||||||||
- In the `swh-jenkins-jobs <https://forge.softwareheritage.org/source/swh-jenkins-jobs>`__ repository, open the | |||||||||||||||||||
``jobs/swh-packages.yaml`` and add a section for the new repository as for the others | |||||||||||||||||||
(`Example <https://forge.softwareheritage.org/rCJSWHdd5b3a1192cb45c07103be199af8c2a74478746e>`__) | |||||||||||||||||||
- `Configure the post-receive hook on phabricator <https://wiki.softwareheritage.org/wiki/Debian_packaging#Setting_up_the_repository_on_Phabricator>`__ | |||||||||||||||||||
- `Setting up the jenkins jobs <https://wiki.softwareheritage.org/wiki/Debian_packaging#Setting_up_the_Jenkins_jobs>`__ | |||||||||||||||||||
`Setting up debian builds <https://wiki.softwareheritage.org/wiki/Debian_packaging#Git_repositories_for_Debian_packages>`__ | |||||||||||||||||||
------------------------- | |||||||||||||||||||
Documentation updates | |||||||||||||||||||
--------------------- | |||||||||||||||||||
Done Inline ActionsCan you move the link inside the paragraph? vlorentz: Can you move the link inside the paragraph? | |||||||||||||||||||
Done Inline Actionssure, i did not know how to properly add this. ardumont: sure, i did not know how to properly add this.
Also, initially the paragraph was empty. | |||||||||||||||||||
- Documentation repository is located in the `swh-docs | |||||||||||||||||||
<https://forge.softwareheritage.org/source/swh-docs/>`__ | |||||||||||||||||||
- Add the new module dependency in the top-level ``requirements-swh.txt`` and | |||||||||||||||||||
``requirements-swh-dev.txt`` | |||||||||||||||||||
- Add the new module entry in ``docs/index.rst`` with a concise description of the | |||||||||||||||||||
module | |||||||||||||||||||
:: | |||||||||||||||||||
:ref:`swh.auth <swh-auth>` | |||||||||||||||||||
low-level library used by modules needing keycloak authentication | |||||||||||||||||||
... | |||||||||||||||||||
# at the end of the index page | |||||||||||||||||||
swh.auth <swh-auth/index> | |||||||||||||||||||
- ensure this builds fine locally (e.g run `tox`, then `make -C docs`) | |||||||||||||||||||
- Then open a diff to advertise the new documentation entrypoints (`Example <https://forge.softwareheritage.org/D5327>`__) | |||||||||||||||||||
Done Inline Actions
vlorentz: |
I try to avoid stop words in anchor names. What about .. _tutorial-new-package:?