Admin guides in docs: overview, configuration, writing an admin half and translating (A-46)

Ouverte
#3,463 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
35/100
Type d'issue
Documentation
Clarté
Clairement spécifiée
Activité
Active
Stack technique
csharp
Domaine
documentation

Piste de recherche

Start with docs/planning/admin-technical-spec.md sections 2.5, 5.1, 6 and 10.8, then compare each claim with the current branch; the issue says planned behavior should be omitted. Create the four named pages, link them from the listed READMEs and docs, and follow the acceptance checklist, including the plugin example, configuration comparison and #3178 update. Done means all links resolve, Markdown lint passes, and each acceptance item is met.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

area:admin type:docs

Problem

The admin is about to be released, and docs/ describes it for an operator of the reference host only. What exists:

  • docs/host-configuration.md, section "Admin": the keys of FluentCms:Admin.
  • docs/docker.md, section "The admin": turning it on in the image.
  • admin/README.md: the projects and their rules, for a contributor to this repository.
  • The README of each package and of each template, and decision record 0007 on the sign-in.

What a reader finds only in the technical specification, a planning document, or nowhere:

  • Which distribution to take, and how to open the admin for the first time.
  • config.json. Its members, their rules and defaults are in section 2.5 alone, and the two settings of an API host for an admin on another origin in 6.4 alone.
  • Writing an admin half (row 8.1). The contract is section 5.1 and the public types of FluentCMS.Admin.Abstractions; the template's README describes the files it wrote, not the other kinds of contribution.
  • Translating. AQ14 promises a contribution guide for translations, and A-53 makes a translation a set of files.

Hosting the static build is docs/admin-hosting.md, which A-43 writes; section 10.8 named it under both issues.

Proposal

Four pages, each linked from the README, from docs/docker.md and from the READMEs of the packages and templates it concerns:

  • docs/admin.md. What the admin is, the three distributions and whom each is for, the first sign-in with the first administrator of docs/docker.md, the supported browsers (AQ12), the language and formats of a user (A-41), and where the other pages are.
  • docs/admin-configuration.md. Each member of config.json with its rule, its default and an example; how the reference host builds it from FluentCms:Admin; an admin on another origin, with the CORS setting and the client registration written out; what the client fluentcms-admin must be when a host configures it itself (public, with PKCE, the five scopes and the redirect URIs of the served admin); branding, the offered cultures and the preview origins; and the pre-authentication rate limit, which the files of /admin count against, with the key that raises it (#3178).
  • docs/admin-plugins.md. Starting from dotnet new fluentcms-plugin: the project and what it may reference, the manifest and its test, each kind of contribution with an example (a page, a menu item, a settings page, a field editor, a list cell, an entry action, a bulk action, a field action, a widget, a service for other halves), the services the admin gives a component, access for the site and for the instance, lazy loading and the BlazorWebAssemblyLazyLoad line, AdminRange and versions, the half's own records and the check against the OpenAPI document, its resources and its menu texts per culture, the accessibility rules of a field editor, and what a half cannot do. Each example is a file of the template or of the sample half of the tests and names it, so that the build keeps it true.
  • docs/admin-translating.md. The resource files of each assembly and how to name them, the test of the keys, the pseudo-cultures and how to run the admin in one, placeholders and right to left, and how to send a translation.

Each statement is checked against the code of the branch, and a behaviour that is planned and not built is left out.

Acceptance

  • The four pages exist and pass the Markdown lint, and every link resolves
  • A reader makes a plugin from the template, adds a contribution of a kind the template lacks by following docs/admin-plugins.md, and its manifest test passes; the lane does so once and says so in the pull request
  • Every member of AdminConfiguration and every key of AdminOptions is in docs/admin-configuration.md, and a test or a review step named in the pull request compares them
  • The README, docs/docker.md, docs/host-configuration.md and the READMEs of the admin packages and of the three templates link the pages
  • The item of #3178 on the rate limit of the static files is ticked as documented

Design: docs/planning/admin-technical-spec.md, sections 2.5, 5.1, 6 and 10.8 (A-46). Rows 8.1, 11.4. Takes one item of #3178. Needs A-41, A-53, A-43 and A-44, whose work it describes. Size: M.

Langage dominant
C#
Étoiles
567
Forks
107
Merge moyen
1 h 19 min
PR mergées (30 j)
353

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de fluentcms/FluentCMS

Toutes les issues de fluentcms/FluentCMS

Issues similaires

Plus d'issues C#

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.