Commit 8417fd7a authored by Laurent Peuch's avatar Laurent Peuch
Browse files

doc: add README.rst

parent bdef37d0176d
Cube Doctor
===========
Cube doctor is a tool used to send generated refactoring and QA improvement MR
to logilab's projects.
Usage
-----
CLI pattern looks like:
::
GITLAB_TOKEN=... python3 doctor_hg.py [-h] [-a] [-i] [-m] [-n NUMBER] [-q QUERY] {fix-README,add-tox,add-pytest-deprecated-warnings-cmd}
Example:
::
GITLAB_TOKEN=... python3 doctor_hg.py fix-README
Explanation
-----------
The current workflow for cube doctor is:
- select a refactoring command (for example fix-README will rename a README into README.rst and do other needed stuff)
- download our generated heptapod.trig that contains informations about all the public repositories of logilab's forge https://forge.extranet.logilab.fr/
- do a sparql query on that heptapod.trig to select repositories to target (each command has a default query to select only repositories on which it will be able to work)
- alternatively, if no query is provided (but right now all commands provides a query) all cubes of the cubicweb/cube group will be used
- for each of those cube, apply the refactoring command and show what it would have done but do nothing
- except if the "-a"/"--apply" flag is provided then the modification is pushed and a new merge request is created (and it is logged in create_mr.log)
- or if the "-i"/"--interactif" flag is provided then for each cube the user will be prompt to tell if it wants to create a MR
Commands
--------
Current existing refactoring commands
fix-README
~~~~~~~~~~
This command will:
- rename README to README.rst
- replace "README" by "README.rst" in setup.py if present
- replace "README" by "README.rst" in MANIFEST.in if present or add "include README.rst" at the end of it
add-pytest-deprecated-warnings-cmd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command will:
- add :ref:`git+https://github.com/psycojoker/pytest-capture-deprecatedwarnings` to the deps section of the [testenv] of the tox.ini
- or if a dev-requirements.txt exist, add it into it instead
- modify .gitlag-ci.yml "py3" section to add "py3-deprecated-warnings.json" has an artifact
add-tox
~~~~~~~
This command is a bit WIP. It will:
- add a base tox.ini in a repository if it doesn't exist
- it will also launch this tox and fail if the tox fails
Command CLI arguments
---------------------
All commands share the same CLI arguments. They are:
::
-a, --apply
If used a merge request will be created with the modifcations.
Default value: False
-i, --interactif
If used the user will be prompt before created a merge request (a "hg
diff" and "hg status" will be run before to show the modifications)
-a/--apply will overwrite this argument
Default value: False
-m, --merge-when-pipeline-succeeds
If used the created merged request will be set to be merged if the
tests succeeds. Won't have any effect if no merge request is created.
Default value: False
-n, --number
Limit the number of cubes of which to run the command
Default value: None (equal to "all cubes")
-q, --query
Additional conditions to pass to the sparql query SELECT section.
Sparql query reference
----------------------
The sparql base query looks like this:
::
prefix lgg: <http://data.logilab.fr/logigraphe/>
prefix lon: <http://data.logilab.fr/ontology/network/>
prefix dep: <http://ontologi.es/doap-deps#>
prefix doap: <http://usefulinc.com/ns/doap#>
SELECT ?projectId
WHERE {
?project a doap:Project .
?project doap:name ?projectName .
?project lgg:heptapod_id ?projectId .
?project lgg:is_cube true
} ORDER BY ?projectName
And all the field of a project looks like this (but this evolve quickly so
check the heptapod.trig to be sure):
::
lgg:has_black false ;
lgg:has_capture_deprecated_warnings true ;
lgg:has_check_manifest true ;
lgg:has_doc false ;
lgg:has_flake8 true ;
lgg:has_from_forge false ;
lgg:has_gitlab_ci true ;
lgg:has_mypy false ;
lgg:has_py2_tests true ;
lgg:has_py3_tests true ;
lgg:has_pytest true ;
lgg:has_readme_rst false ;
lgg:has_readthedocs false ;
lgg:has_tox true ;
lgg:heptapod_id 143 ;
lgg:is_cube true ;
lgg:is_new_format true ;
lgg:last_activity_at "2020-09-17T07:16:55.785000"^^xsd:dateTime ;
lgg:visibility "public" ;
dc:description "cubicweb / cubes / activitystream" ;
dc:title "cubicweb-activitystream" ;
doap:name "cubicweb-activitystream" ;
doap:release <https://forge.extranet.logilab.fr/cubicweb/cubes/activitystream/-/releases/0.2.0> .
So, an example query to only select the activitystream could be done like this:
::
GITLAB_TOKEN=... python3 doctor_hg.py fix-README -q '?project doap:name "cubicweb-activitystream"'
Markdown is supported
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