Problem/Motivation

README.md is empty. Everything the module does is described only in the project page's two paragraphs, in change records, and in docblocks — which leaves a site builder guessing at the settings, an operator at the Drush commands and cron behaviour, and a connector maintainer at which of the capability interfaces to implement.

Proposed resolution

A README following the drupal.org README template, with one section per audience:

  • Requirements, installation, configuration (every setting and permission).
  • Subscribers: the subscribe flow, the management page and its actions, billing history, what cancellation means.
  • Site builders and administrators: plans, subscriptions, charges, role handling, theming, mails, the JSON endpoints.
  • Operators: cron, dunning in practice, the Drush commands.
  • Connector maintainers: the attribute, the base interface, the capability interfaces, charge-based connectors, post-purchase login, testing.
  • Developers: usage raters, the tax/invoice seam, events, the engine's API.
  • Updating, and the change-record policy.

Remaining tasks

Write it; review it against the code; merge.

User interface changes

None.

API changes

None.

Data model changes

None.

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

colan created an issue. See original summary.

colan’s picture

Status: Active » Needs review

  • colan committed 0b1073ae on 1.0.x
    Merge branch '3629098-document-the-module' into '1.0.x'
    
    Resolve #...

  • colan committed 2798a633 on 1.0.x
    Issue #3629098: Link the Token module
    
    Co-Authored-By: Claude Fable 5.1...

  • colan committed 15d29690 on 1.0.x
    Issue #3629098: Let GitLab generate the table of contents
    
    Co-Authored-...

  • colan committed caaf0168 on 1.0.x
    Issue #3629098: Document the module in README.md
    
    One section per...
colan’s picture

Status: Needs review » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

colan’s picture

One more README commit landed against this issue before it closes, on the #3630969: Refuse an upgrade while a period charge is open or the subscription is past due, and validate the currency on plan change MR (merge request 33), since commit e41b3bf on 1.0.x added Tool API integration (src/Tool/SubscriptionTools.php, service subscription_manager.tools) with no README coverage. The commit adds:

  • A line under Requirements: Tool API is optional, like Token.
  • A "Tool API tools" subsection under the site-builder section listing the five tools with the permission or access check each one has (list_plans and sync_plans: Administer Subscription plans; list_overdue_subscriptions: Administer Subscription entities; refresh_subscription: update access on the subscription; list_user_subscriptions: administrators for anyone, a subscriber for themselves), that none moves money or changes a subscription, that the result fields are the curated ones the JSON endpoints use, that refresh and sync make one unthrottled remote call per invocation (#3629972: Dedupe and rate-limit the remote calls made on registration, login and the subscribe and portal routes), and that the attributes are inert without Tool API.
  • A line under Permissions: list_user_subscriptions takes the user as an entity input with a view check, so a subscriber listing their own subscriptions also needs core's Access user profiles. Documented rather than changed; relaxing the check for the self case would be a small follow-up if wanted.

The beta7 release notes should name the feature too, since it shipped on 1.0.x between the audit rounds.

  • colan committed e4093119 on 1.0.x
    Issue #3629098: Document the Tool API tools, their gates and the profile...

  • colan committed a3d9c37e on 1.0.x
    Issue #3629098: Say which Tool API version the tools need
    
    The attribute...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.