Page MenuHomeSoftware Heritage

Add an how-to add a new swh package
ClosedPublic

Authored by ardumont on Mon, Jul 5, 3:55 PM.

Details

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
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

ardumont created this revision.
  • Fix badly named index (after multiple renaming, this one got forgotten)
  • Adapt some sentence formulations
  • Use more sphinx stanza, namely use named links.
  • Improve sentence phrasing again

Align commit message with the diff description

Merge tag edition into 1 more logical step

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 ↗(On Diff #21495)

I try to avoid stop words in anchor names. What about .. _tutorial-new-package:?

41 ↗(On Diff #21495)

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)

docs/tutorials/add-a-new-module.rst
23–24 ↗(On Diff #21495)
33 ↗(On Diff #21495)
45–47 ↗(On Diff #21495)

This should probably explain when they should be enabled

104–105 ↗(On Diff #21495)

Can you move the link inside the paragraph?

123–128 ↗(On Diff #21495)

Thanks ;)

I'll attend to your suggestions during the day.

docs/tutorials/add-a-new-module.rst
45–47 ↗(On Diff #21495)

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 ↗(On Diff #21495)

sure, i did not know how to properly add this.
Also, initially the paragraph was empty.

ardumont added inline comments.
docs/tutorials/add-a-new-module.rst
1 ↗(On Diff #21495)

Sure.

Note that i think it's an how to though (see diff description) but fine.

ardumont marked an inline comment as done.

Adapt according to review

ardumont edited the summary of this revision. (Show Details)

Fix couple of inconsistencies

ardumont retitled this revision from Add an how-to add a new swh module to Add an how-to add a new swh package.Tue, Jul 6, 5:24 PM
This revision was not accepted when it landed; it landed in state Needs Review.Wed, Jul 7, 10:19 AM
This revision was automatically updated to reflect the committed changes.