From 9282b0512f09ead0bf3d15fdf24117ea39a4fad5 Mon Sep 17 00:00:00 2001 From: James Elliott Date: Tue, 3 Jan 2023 22:44:14 +1100 Subject: [PATCH] docs: improve server override docs (#4687) --- docs/content/en/policies/versioning.md | 20 +++++++++++-------- .../reference/guides/internationalization.md | 2 ++ .../guides/notification-templates.md | 7 ++++--- .../guides/server-asset-overrides.md | 18 +++++++---------- .../shortcodes/table-i18n-overrides.html | 5 +++++ 5 files changed, 30 insertions(+), 22 deletions(-) create mode 100644 docs/layouts/shortcodes/table-i18n-overrides.html diff --git a/docs/content/en/policies/versioning.md b/docs/content/en/policies/versioning.md index 5853f35dd..0906400bd 100644 --- a/docs/content/en/policies/versioning.md +++ b/docs/content/en/policies/versioning.md @@ -10,13 +10,17 @@ aliases: --- The __Authelia__ team aims to abide by the [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) policy. This -means that we use the format `major.minor.patch` for our version numbers, where a change to `major` denotes a breaking -change which will likely require user interaction to upgrade, `minor` which denotes a new feature, and `patch` denotes a -fix. +means that we use the format `..` for our version numbers, where a change to `major` denotes a +breaking change which will likely require user interaction to upgrade, `minor` which denotes a new feature, and `patch` +denotes a fix. It is therefore recommended users do not automatically upgrade the `minor` version without reading the patch notes, and it's critically important users do not upgrade the `major` version without reading the patch notes. You should pin your -version to `4.37` for example to prevent automatic upgrades from negatively affecting you. +version to `4.37` for example to prevent automatic upgrades of the `minor` version, or pin your version to `4` to +prevent automatic upgrade of the `major` version. + +We generally do not recommend automated upgrades of critical systems but instead recommend ensuring you are notified an +upgrade exists. ## Exceptions @@ -33,7 +37,7 @@ Notable Advanced Customizations: - Templates: - Email - Content Security Policy header -- Localization Assets +- Localization / Internationalization Assets ### Breaking Changes @@ -47,6 +51,6 @@ Notable examples: - OpenID Connect 1.0 - File Filters -The reasoning is as we develop these features there may be mistakes and we may need to make a change that should be -considered breaking. As these features graduate from their status to generally available they will move into our -standard versioning policy from this exception. +The reasoning is as we develop these features there may be mistakes and we may need to make a change that would normally +be considered a breaking change. As these features graduate from their status to generally available they will move into +our standard versioning policy and lose their exception status. diff --git a/docs/content/en/reference/guides/internationalization.md b/docs/content/en/reference/guides/internationalization.md index eb204bee9..dadf6062c 100644 --- a/docs/content/en/reference/guides/internationalization.md +++ b/docs/content/en/reference/guides/internationalization.md @@ -15,3 +15,5 @@ toc: true ## Web Portal Internationalization {{% table-i18n-locales %}} + +Information about overriding the web portal internationalization is available from the [Server Asset Overrides Reference Guide](./server-asset-overrides.md). diff --git a/docs/content/en/reference/guides/notification-templates.md b/docs/content/en/reference/guides/notification-templates.md index 95a30e9e5..cfc078dd9 100644 --- a/docs/content/en/reference/guides/notification-templates.md +++ b/docs/content/en/reference/guides/notification-templates.md @@ -20,9 +20,9 @@ This guide effectively documents the usage of the ## Important Notes -1. The templates are not covered by our stability guarantees. While we aim to avoid changes to the templates which - would cause users to have to manually change them changes may be necessary in order to facilitate bug fixes or - generally improve the templates. +1. The templates are not covered by our stability guarantees as per our [Versioning Policy]. While we aim to avoid + changes to the templates which would cause users to have to manually change them changes may be necessary in order to + facilitate bug fixes or generally improve the templates. 1. It is your responsibility to ensure your templates are up to date. We make no efforts in facilitating this. 2. We may not be able to offer any direct support in debugging these templates. We only offer support and fixes to the official templates. @@ -82,3 +82,4 @@ Several functions are implemented with the email templates. See the [server_name]: ../../configuration/notifications/smtp.md#tls [sender]: ../../configuration/notifications/smtp.md#sender [identifier]: ../../configuration/notifications/smtp.md#identifier +[Versioning Policy]: ../../policies/versioning.md diff --git a/docs/content/en/reference/guides/server-asset-overrides.md b/docs/content/en/reference/guides/server-asset-overrides.md index 966401668..a593af76c 100644 --- a/docs/content/en/reference/guides/server-asset-overrides.md +++ b/docs/content/en/reference/guides/server-asset-overrides.md @@ -39,8 +39,8 @@ the language itself, or adding a variant form of that language. If you'd like su to make a PR. We also encourage people to make PR's for variants where the difference in the variants is significant.* *__Important Note__ Users wishing to override the locales files should be aware that we do not provide any guarantee -that the file will not change in a breaking way between releases. Users who planning to utilize these -overrides should either check for changes to the files in the +that the file will not change in a breaking way between releases as per our [Versioning Policy]. Users who planning to +utilize these overrides should either check for changes to the files in the [en](https://github.com/authelia/authelia/tree/master/internal/server/locales/en) translation prior to upgrading or [Contribute](../../contributing/prologue/translations.md) their translation to ensure it is maintained.* @@ -72,12 +72,8 @@ Each file in a locale directory represents a translation namespace. The list of List of supported languages and variants: -| Description | Language | Additional Variants | Location | -|:---------------------:|:--------:|:-------------------:|:--------------------:| -| English | en | N/A | locales/en/*.json | -| Spanish | es | N/A | locales/es/*.json | -| German | de | N/A | locales/de/*.json | -| French | fr | N/A | locales/fr/*.json | -| Russian | ru | N/A | locales/ru/*.json | -| Swedish | sv | sv-SE (Sweden) | locales/sv/*.json | -| Chinese (Traditional) | zh-TW | N/A | locales/zh-TW/*.json | +{{% table-i18n-overrides %}} + +More information may be available from the [Internationalization Reference Guide](./internationalization.md). + +[Versioning Policy]: ../../policies/versioning.md diff --git a/docs/layouts/shortcodes/table-i18n-overrides.html b/docs/layouts/shortcodes/table-i18n-overrides.html new file mode 100644 index 000000000..6b5c37ec8 --- /dev/null +++ b/docs/layouts/shortcodes/table-i18n-overrides.html @@ -0,0 +1,5 @@ +| Language | Locale | Override Path | +|:--------------:|:-------------:|:----------------------------:| +{{- range $.Site.Data.languages.languages }} +| {{ .display }} | {{ .locale }} | locales/{{ .locale }}/*.json | +{{- end }}