Details

Reviewers

vsellier
vlorentz

Group Reviewers

Reviewers

Maniphest Tasks

T3179: Add an how-to create a new swh package

Commits

rDDOCe9e838d43ad6: Add an how-to add a new swh package

Summary

The following document demonstrates how to create a new swh package in the current swh
phabricator instance and reference it so the Continuous Integration (CI) is able to
build the new module.

It's problem oriented so it's more an how-to [1]. I've added it to the "tutorials" tree
though as we don't have a "how to" section yet...

It might be even possible this could go to the "contribute" section but as not all steps
could be done from an external contributor, I kept it out.

Anyway, feel free to propose some improvments ;)

[1] https://documentation.divio.com/ (that's the approach we are trying to reach)

Related to T3179

Test Plan

make -C docs is happy

Diff Detail

Repository

rDDOC Development documentation

Branch

master

Lint

No Linters Available

Unit

No Unit Test Coverage

Build Status

Buildable 22465
Build 34992: arc lint + arc unit

Event Timeline

ardumont requested review of this revision.Jul 5 2021, 3:55 PM

ardumont created this revision.

Harbormaster completed remote builds in B22462: Diff 21483.Jul 5 2021, 3:55 PM

ardumont edited the summary of this revision. (Show Details)Jul 5 2021, 3:56 PM

ardumont edited the summary of this revision. (Show Details)Jul 5 2021, 3:59 PM

ardumont edited the summary of this revision. (Show Details)Jul 5 2021, 4:03 PM

nice!

Fix badly named index (after multiple renaming, this one got forgotten)
Adapt some sentence formulations

Harbormaster completed remote builds in B22464: Diff 21485.Jul 5 2021, 4:53 PM

ardumont edited the summary of this revision. (Show Details)Jul 5 2021, 4:59 PM

Use more sphinx stanza, namely use named links.
Improve sentence phrasing again

Harbormaster completed remote builds in B22465: Diff 21486.Jul 5 2021, 5:19 PM

Align commit message with the diff description

Harbormaster completed remote builds in B22466: Diff 21487.Jul 5 2021, 5:19 PM

Merge tag edition into 1 more logical step

Harbormaster completed remote builds in B22469: Diff 21495.Jul 5 2021, 5:43 PM

Could you rename "new module" to "new repository" everywhere? In Python, modules are single files (or sometimes packages too, but this is neither)

docs/tutorials/add-a-new-module.rst
1	I try to avoid stop words in anchor names. What about `.. _tutorial-new-package:`?
41	Define 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 added inline comments.Jul 6 2021, 10:04 AM

docs/tutorials/add-a-new-module.rst
23–24
33
45–47	This should probably explain when they should be enabled
104–105	Can you move the link inside the paragraph?
123–128

Thanks ;)

I'll attend to your suggestions during the day.

docs/tutorials/add-a-new-module.rst
45–47	yes, 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...
104–105	sure, i did not know how to properly add this. Also, initially the paragraph was empty.