From d2f6b773c2cffc4c90c5b8c4ab0146df1845226d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 13 Mar 2026 18:56:25 +0000 Subject: [PATCH 1/2] chore(docs): Update Terraform documentation (#3) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../modules/landscape-scalable/README.md | 100 +++++++++--------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/terraform/product/modules/landscape-scalable/README.md b/terraform/product/modules/landscape-scalable/README.md index eee3f1ea..b2c0483c 100644 --- a/terraform/product/modules/landscape-scalable/README.md +++ b/terraform/product/modules/landscape-scalable/README.md @@ -50,71 +50,71 @@ This module uses the [Landscape Server charm module](https://github.com/canonica ## Requirements -| Name | Version | -| ------------------------------------------------------------------------- | ------- | +| Name | Version | +|------|---------| | [terraform](#requirement\_terraform) | >= 1.10 | -| [juju](#requirement\_juju) | ~> 1.0 | +| [juju](#requirement\_juju) | ~> 1.0 | ## Providers -| Name | Version | -| ---------------------------------------------------- | ------- | -| [juju](#provider\_juju) | ~> 1.0 | +| Name | Version | +|------|---------| +| [juju](#provider\_juju) | ~> 1.0 | ## Modules -| Name | Source | Version | -| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------- | -| [haproxy](#module\_haproxy) | git::https://github.com/canonical/haproxy-operator.git//terraform/charm/haproxy | haproxy-rev331 | -| [landscape\_server](#module\_landscape\_server) | ../../../charm | n/a | -| [postgresql](#module\_postgresql) | git::https://github.com/canonical/postgresql-operator.git//terraform | v16/1.165.0 | +| Name | Source | Version | +|------|--------|---------| +| [haproxy](#module\_haproxy) | git::https://github.com/canonical/haproxy-operator.git//terraform/charm/haproxy | haproxy-rev331 | +| [landscape\_server](#module\_landscape\_server) | ../../../charm | n/a | +| [postgresql](#module\_postgresql) | git::https://github.com/canonical/postgresql-operator.git//terraform | v16/1.165.0 | ## Resources -| Name | Type | -| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| [juju_application.hostagent_messenger_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | -| [juju_application.http_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | -| [juju_application.lb_certs](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | -| [juju_application.rabbitmq_server](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | -| [juju_application.ubuntu_installer_attach_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | -| [juju_integration.landscape_server_haproxy](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | -| [juju_integration.landscape_server_hostagent_messenger_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | -| [juju_integration.landscape_server_http_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | -| [juju_integration.landscape_server_inbound_amqp](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | -| [juju_integration.landscape_server_outbound_amqp](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | -| [juju_integration.landscape_server_postgresql_legacy](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | -| [juju_integration.landscape_server_postgresql_modern](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | -| [juju_integration.landscape_server_rabbitmq_server](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | -| [juju_integration.landscape_server_tls_certificates](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | +| Name | Type | +|------|------| +| [juju_application.hostagent_messenger_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | +| [juju_application.http_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | +| [juju_application.lb_certs](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | +| [juju_application.rabbitmq_server](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | +| [juju_application.ubuntu_installer_attach_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application) | resource | +| [juju_integration.landscape_server_haproxy](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | +| [juju_integration.landscape_server_hostagent_messenger_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | +| [juju_integration.landscape_server_http_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | +| [juju_integration.landscape_server_inbound_amqp](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | +| [juju_integration.landscape_server_outbound_amqp](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | +| [juju_integration.landscape_server_postgresql_legacy](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | +| [juju_integration.landscape_server_postgresql_modern](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | +| [juju_integration.landscape_server_rabbitmq_server](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | +| [juju_integration.landscape_server_tls_certificates](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | | [juju_integration.landscape_server_ubuntu_installer_attach_ingress](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration) | resource | -| [juju_machine.landscape_server](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/machine) | resource | +| [juju_machine.landscape_server](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/machine) | resource | ## Inputs -| Name | Description | Type | Default | Required | -| ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | :------: | -| [haproxy](#input\_haproxy) | Configuration for the (legacy) HAProxy charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "haproxy")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      default_timeouts            = "queue 60000, connect 5000, client 120000, server 120000"
      global_default_bind_options = "no-tlsv10"
      services                    = ""
      ssl_cert                    = "SELFSIGNED"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@22.04")
    units       = optional(number, 1)
  })
| `null` | no | -| [hostagent\_messenger\_ingress](#input\_hostagent\_messenger\_ingress) | Configuration for the hostagent messenger ingress configurator charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "hostagent-messenger-ingress")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      external-grpc-port = "6554"
      hostname           = "landscape.local"
      backend-protocol   = "https"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `null` | no | -| [http\_ingress](#input\_http\_ingress) | Configuration for the HTTP ingress configurator charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "http-ingress")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      paths                      = "/"
      hostname                   = "landscape.local"
      header-rewrite-expressions = "X-Forwarded-Proto:https"
      allow-http                 = "true"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `null` | no | -| [landscape\_server](#input\_landscape\_server) | Configuration for the Landscape Server charm. | 
object({
    app_name = optional(string, "landscape-server")
    channel  = optional(string, "25.10/edge")
    config = optional(map(string), {
      autoregistration               = "true"
      landscape_ppa                  = "ppa:landscape/self-hosted-beta"
      min_install                    = "true"
      root_url                       = "https://landscape.local/"
      enable_hostagent_messenger     = "true"
      enable_ubuntu_installer_attach = "true"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `{}` | no | -| [lb\_certs](#input\_lb\_certs) | Configuration for the self-signed-certificates charm (for internal HAProxy TLS). Set to null to skip deployment. | 
object({
    app_name    = optional(string, "lb-certs")
    channel     = optional(string, "1/stable")
    config      = optional(map(string), {})
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `{}` | no | -| [model\_uuid](#input\_model\_uuid) | UUID of the Juju model to deploy Landscape Server to. | `string` | n/a | yes | -| [postgresql](#input\_postgresql) | Configuration for the PostgreSQL charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "postgresql")
    channel  = optional(string, "16/stable")
    config = optional(map(string), {
      plugin_plpython3u_enable     = "true"
      plugin_ltree_enable          = "true"
      plugin_intarray_enable       = "true"
      plugin_debversion_enable     = "true"
      plugin_pg_trgm_enable        = "true"
      experimental_max_connections = "500"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `{}` | no | -| [rabbitmq\_server](#input\_rabbitmq\_server) | Configuration for the RabbitMQ charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "rabbitmq-server")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      consumer-timeout = "259200000"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `{}` | no | -| [ubuntu\_installer\_attach\_ingress](#input\_ubuntu\_installer\_attach\_ingress) | Configuration for the Ubuntu installer attach ingress configurator charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "ubuntu-installer-attach-ingress")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      external-grpc-port = "50051"
      hostname           = "landscape.local"
      backend-protocol   = "https"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `null` | no | +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [haproxy](#input\_haproxy) | Configuration for the (legacy) HAProxy charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "haproxy")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      default_timeouts            = "queue 60000, connect 5000, client 120000, server 120000"
      global_default_bind_options = "no-tlsv10"
      services                    = ""
      ssl_cert                    = "SELFSIGNED"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@22.04")
    units       = optional(number, 1)
  })
| `null` | no | +| [hostagent\_messenger\_ingress](#input\_hostagent\_messenger\_ingress) | Configuration for the hostagent messenger ingress configurator charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "hostagent-messenger-ingress")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      external-grpc-port = "6554"
      hostname           = "landscape.local"
      backend-protocol   = "https"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `null` | no | +| [http\_ingress](#input\_http\_ingress) | Configuration for the HTTP ingress configurator charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "http-ingress")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      paths                      = "/"
      hostname                   = "landscape.local"
      header-rewrite-expressions = "X-Forwarded-Proto:https"
      allow-http                 = "true"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `null` | no | +| [landscape\_server](#input\_landscape\_server) | Configuration for the Landscape Server charm. | 
object({
    app_name = optional(string, "landscape-server")
    channel  = optional(string, "25.10/edge")
    config = optional(map(string), {
      autoregistration               = "true"
      landscape_ppa                  = "ppa:landscape/self-hosted-beta"
      min_install                    = "true"
      root_url                       = "https://landscape.local/"
      enable_hostagent_messenger     = "true"
      enable_ubuntu_installer_attach = "true"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `{}` | no | +| [lb\_certs](#input\_lb\_certs) | Configuration for the self-signed-certificates charm (for internal HAProxy TLS). Set to null to skip deployment. | 
object({
    app_name    = optional(string, "lb-certs")
    channel     = optional(string, "1/stable")
    config      = optional(map(string), {})
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `{}` | no | +| [model\_uuid](#input\_model\_uuid) | UUID of the Juju model to deploy Landscape Server to. | `string` | n/a | yes | +| [postgresql](#input\_postgresql) | Configuration for the PostgreSQL charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "postgresql")
    channel  = optional(string, "16/stable")
    config = optional(map(string), {
      plugin_plpython3u_enable     = "true"
      plugin_ltree_enable          = "true"
      plugin_intarray_enable       = "true"
      plugin_debversion_enable     = "true"
      plugin_pg_trgm_enable        = "true"
      experimental_max_connections = "500"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `{}` | no | +| [rabbitmq\_server](#input\_rabbitmq\_server) | Configuration for the RabbitMQ charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "rabbitmq-server")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      consumer-timeout = "259200000"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `{}` | no | +| [ubuntu\_installer\_attach\_ingress](#input\_ubuntu\_installer\_attach\_ingress) | Configuration for the Ubuntu installer attach ingress configurator charm. Set to null to skip deployment. | 
object({
    app_name = optional(string, "ubuntu-installer-attach-ingress")
    channel  = optional(string, "latest/edge")
    config = optional(map(string), {
      external-grpc-port = "50051"
      hostname           = "landscape.local"
      backend-protocol   = "https"
    })
    constraints = optional(string, "arch=amd64")
    resources   = optional(map(string), {})
    revision    = optional(number)
    base        = optional(string, "ubuntu@24.04")
    units       = optional(number, 1)
  })
| `null` | no | ## Outputs -| Name | Description | -| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [admin\_email](#output\_admin\_email) | Administrator email from the Landscape Server config. | -| [admin\_password](#output\_admin\_password) | Administrator password from the Landscape Server config (sensitive). | -| [applications](#output\_applications) | The charms included in the module. | -| [haproxy\_self\_signed](#output\_haproxy\_self\_signed) | Indicates whether legacy HAProxy is using a self-signed TLS certificate. Null for 26.04+ deployments with internal HAProxy or when haproxy is not deployed. | -| [has\_internal\_haproxy](#output\_has\_internal\_haproxy) | Indicates whether the deployment uses internal HAProxy (26.04 beta+) instead of the legacy external HAProxy charm. | -| [has\_modern\_amqp\_relations](#output\_has\_modern\_amqp\_relations) | Indicates whether the deployment uses the modern inbound/outbound AMQP endpoints. | -| [has\_modern\_postgres\_interface](#output\_has\_modern\_postgres\_interface) | Indicates whether the deployment supports the modern PostgreSQL charm interface. | -| [ingress\_configurators\_deployed](#output\_ingress\_configurators\_deployed) | Indicates whether ingress configurator charms are deployed for external load balancer integration. | -| [registration\_key](#output\_registration\_key) | Registration key from the Landscape Server config. | +| Name | Description | +|------|-------------| +| [admin\_email](#output\_admin\_email) | Administrator email from the Landscape Server config. | +| [admin\_password](#output\_admin\_password) | Administrator password from the Landscape Server config (sensitive). | +| [applications](#output\_applications) | The charms included in the module. | +| [haproxy\_self\_signed](#output\_haproxy\_self\_signed) | Indicates whether legacy HAProxy is using a self-signed TLS certificate. Null for 26.04+ deployments with internal HAProxy or when haproxy is not deployed. | +| [has\_internal\_haproxy](#output\_has\_internal\_haproxy) | Indicates whether the deployment uses internal HAProxy (26.04 beta+) instead of the legacy external HAProxy charm. | +| [has\_modern\_amqp\_relations](#output\_has\_modern\_amqp\_relations) | Indicates whether the deployment uses the modern inbound/outbound AMQP endpoints. | +| [has\_modern\_postgres\_interface](#output\_has\_modern\_postgres\_interface) | Indicates whether the deployment supports the modern PostgreSQL charm interface. | +| [ingress\_configurators\_deployed](#output\_ingress\_configurators\_deployed) | Indicates whether ingress configurator charms are deployed for external load balancer integration. | +| [registration\_key](#output\_registration\_key) | Registration key from the Landscape Server config. | From 7c8d999c6afc14bfe1a575bf1eb9d4a998d645ba Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 27 Apr 2026 11:01:51 +0000 Subject: [PATCH 2/2] chore: update Copilot collections to v0.12.0 --- .github/.copilot-collections.yaml | 2 +- .../documentation.instructions.md | 116 ++++++++++++++++++ 2 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 .github/instructions/documentation.instructions.md diff --git a/.github/.copilot-collections.yaml b/.github/.copilot-collections.yaml index bc72a544..e390fc13 100644 --- a/.github/.copilot-collections.yaml +++ b/.github/.copilot-collections.yaml @@ -1,5 +1,5 @@ copilot: - version: "v0.7.0" + version: "v0.12.0" collections: - charm-python - pfe-charms diff --git a/.github/instructions/documentation.instructions.md b/.github/instructions/documentation.instructions.md new file mode 100644 index 00000000..bf8a9b01 --- /dev/null +++ b/.github/instructions/documentation.instructions.md @@ -0,0 +1,116 @@ +--- +description: 'Core guidelines for documentation-related suggestions.' +applyTo: 'docs/**/*.md' +--- + +# Documentation instructions for GitHub Copilot + +## Purpose + +This file provides general guidance for reviewing documentation. + +## Core Directives + +This section outlines the absolute order of operations. These rules have the highest priority and must not be violated. + +1. **Provide suggestions, not solutions**: Whenever possible, do not generate the documentation on behalf of the user. Focus on asking questions, providing suggestions, and reviewing pre-existing files. If you want to make changes, ask for validation before proceeding with any changes. +2. **Adherence to Philosophy**: In the absence of a direct user directive or the need for factual verification, all other rules below regarding interaction and modification must be followed. + +## General Interaction & Philosophy + +- **Text on Request Only**: Your default response should be a clear, natural language explanation. Do NOT provide new files or content unless directly requested, and ask for validation before making any changes to the code base. +- **Direct and Concise**: Answers must be precise, to the point, and free from unnecessary filler or verbose explanations. Get straight to the solution without "beating around the bush". +- **Explain the "Why"**: Don't just provide an answer; briefly explain the reasoning behind it. Why is this suggestion clearer, more concise, or easier to understand? + +## General Structure + +In this repository, the documentation is placed in a dedicated `docs` directory. The purpose of the files in this directory is to provide information, instructions, and conceptual understanding of the code for users. + +The top-level `docs` directory should contain an overview or home page called `index.md`. This file should provide a brief description of the project, what needs it serves, and who the primary user base is. + +The rest of the documentation follows the Diataxis framework consisting of four categories of documentation: + +1. **Tutorials**: A practice lesson that walks a user through a learning experience. Tutorials should be placed in the `docs/tutorial` directory, but sometimes they're placed in the top-level `docs` directory. +2. **How-to guides**: Addresses real-world goals or problems by providing practical directions. How-to guides should be placed in the `docs/how-to` directory. +3. **Reference**: Contains technical descriptions of theoretical knowledge. Reference documents should be placed in the `docs/reference` directory. +4. **Explanation**: Provides context and background on topics for the user to understand the bigger picture. Explanation documents should be placed in the `docs/explanation` directory. + +All files should neatly fit into one of these four categories. Do NOT mix content between multiple categories into a single document. Instead, suggest splitting up content into multiple documents to preserve the structure and Diataxis framework. + +### Guidance on tutorials + +A tutorial is a learning-based, end-to-end experience that provides a complete learning journey for the user. The majority of our tutorials walk the user through a basic deployment of the charm in the repository. + +The tutorial should contain the following pieces: + +- **A title**. This title should be more descriptive than "Getting started" + or "Quick guide" which are both indicative of a how-to guide. In a single + statement, what will the user accomplish in the tutorial? +- **An introduction**. In a couple of sentences, introduce the charm and + what the tutorial aims to do. Avoid using a statement like "you will learn", + as that makes an assumption about the user's prior knowledge. Focus + instead on what the user will do or accomplish. +- **What you'll do**. This should be the first section in the tutorial. It + aims to quickly and succinctly establish everything the user will do in the + tutorial. +- **What you'll need**. This section should contain a list of resources, software + or other tools that the user will need before starting the tutorial. In this section, + provide information on the supported architecture(s) like AMD64 or ARM64. + Also include additional information if the + tutorial will require significant resources (CPU, RAM, or disk space). You can + also suggest a Multipass VM to create an isolated testing environment for the tutorial. +- **Set up tutorial model**. The tutorial should begin at this point. Have + the user create Juju model with a predetermined name so that you can reference + the model name throughout the tutorial. +- **Deploy the charm + its dependencies**. If the charm requires any other + charms to successfully deploy, either include in a single section or split into + multiple sections. Use this part of the tutorial to enable any required configurations. + Make sure to briefly explain what the configurations or additional charms are + and why the steps are necessary. Split up important commands into separate + command blocks, and provide explanations between each command. +- **Check the deployment was successful**. Instruct the user to run + ``juju status`` and show example output. If appropriate, also instruct the + user to run ``kubectl get pods -n `` and show the output. + Offer a brief explanation so that the user knows that the deployment was + successful. +- **Some final checkpoint**. Have the user visit a website, change a + configuration, or run an action (maybe some combination of the three). Check + that this step worked; this is more obvious for a website, but you may need + to be creative if you have the user change a configuration or run an action. +- **Tear down the environment**. This should be the final section. Take a moment + to congratulate the user for getting through the tutorial! Have the user + destroy the Juju model that they set up, and if applicable, instruct them to + delete the Multipass VM. + +### Guidance on how-to guides + +- How-to guides should contain a title with the format `# How to...`. The title should +concisely summarize the real-world problem addressed by the document. +- How-to guides should contain at least one CLI command that user can run to address the +problem or achieve the goal. +- Provide instructions or tasks that the user can take to achieve the goal. Avoid gerunds. + + +## Style guide pointers + +- **Spelling**: Use US English for spelling suggestions. +- **Headings**: Use sentence case for headings. Avoid punctuation in headings. Do not skip levels in heading hierarchy. Do not use consecutive headings without intervening text, and suggest removing headings that don't enhance the understanding. Don't overuse `code` styling in headings. +- **Code examples**: Do not use prompt marks (for example, `$` or `#`) in code examples. Do not use comments in code examples; instead, put any comments directly into the text. Whenever possible, split up multiple commands into separate code blocks and provide explanations in between the code blocks. Use Git-flavoured Markdown with fenced code blocks (```) and command examples as shell blocks. +- **Lists**: Only use numbered lists when there is an inherent order to the items. +- **Latin words and phrases**: We can't assume the reader is familiar with Latin words and phrases. Words such as "etc.", "i.e.", "e.g.", "per", "versus", and "via" should be avoided. + +## Small-edit rules for AI agents + +- Avoid describing tasks as "easy" or "simple". +- Preserve existing link targets and code samples formatting. If you change any heading filename or path, update all relative links in `docs/` accordingly. +- Demonstrative pronouns ("this", "these", "those", and "that") should be accompanied by the target noun when there's a risk of ambiguity in the paragraph. An isolated demonstrative pronoun can be used if there's no chance of ambiguity. In cases where a paragraph describes multiple ideas, avoid isolated demonstrative pronouns and be as specific as possible. + +## Changelog guidance + +If you modify a procedure (commands, required versions, prerequisites) and a `docs/changelog.md` exists, add a short note in `docs/changelog.md` summarizing the user-facing change. + +If you add a new file into `docs`, add a short note in `docs/changelog.md` summarizing the user-facing change. + +If there are no user-relevant changes, then the changelog does not need to be updated. + +