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

Abierto
#3,463 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
csharp

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
C#
Estrellas
567
Forks
107
Merge medio
1 h 19 min
PR fusionados (30 d)
353

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de fluentcms/FluentCMS

Todos los issues de fluentcms/FluentCMS

Issues similares

Más issues de C#

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.