Add latest changes from gitlab-org/gitlab@master

2 files changed, 36 insertions, 4 deletions

diff --git a/doc/administration/job_artifacts_troubleshooting.md b/doc/administration/job_artifacts_troubleshooting.md
index 6cdde87cc1d..1dc16d8347c 100644
--- a/doc/administration/job_artifacts_troubleshooting.md
+++ b/doc/administration/job_artifacts_troubleshooting.md
@@ -276,9 +276,9 @@ You can manually remove job artifacts associated with multiple completed jobs wh
 **retaining their job logs** from the [Rails console](operations/rails_console.md).
 A completed job is any job with the status of success, failed, canceled, or skipped.
 
-To delete jobs completed before a specific date:
+To delete job artifacts from jobs completed before a specific date:
 
-1. Select jobs to be deleted:
+1. Select the jobs with artifacts to be deleted:
 
    To select all jobs with artifacts for a single project:
 
@@ -333,9 +333,9 @@ You can manually remove job artifacts associated with multiple completed jobs wh
 **retaining their job logs** from the [Rails console](operations/rails_console.md).
 A completed job is any job with the status of success, failed, canceled, or skipped.
 
-To delete jobs completed before a specific date:
+To delete job artifacts and logs from jobs completed before a specific date:
 
-1. Select the jobs to be deleted:
+1. Select the jobs with artifacts and logs to be deleted:
 
    To select jobs with artifacts for a single project:
 
diff --git a/doc/ci/components/index.md b/doc/ci/components/index.md
index e7c286a507b..830c91616f7 100644
--- a/doc/ci/components/index.md
+++ b/doc/ci/components/index.md
@@ -255,6 +255,38 @@ To publish the component project in the catalog again, you need to [publish a ne
 
 This section describes some best practices for creating high quality component projects.
 
+### Write a clear `README.md`
+
+Each component project should have clear and comprehensive documentation. To
+write a good `README.md` file:
+
+- The documentation should start with a summary of the capabilities that the components in the project provide.
+- If the project contains multiple components, use a [table of contents](../../user/markdown.md#table-of-contents)
+   to help users quickly jump to a specific component's details.
+- Add a `## Components` section with sub-sections like `### Component A` for each component in the project.
+- In each component section:
+  - Add a description of what the component does.
+  - Add at least one YAML example showing how to use it.
+  - If the component uses inputs, add a table showing all inputs with name, description, type, and default value.
+  - If the component uses any variables or secrets, those should be documented too.
+- A `## Contribute` section is recommended if contributions are welcome.
+
+If a component needs more instructions, add additional documentation in a Markdown file
+in the component directory and link to it from the main `README.md` file. For example:
+
+```plaintext
+README.md    # with links to the specific docs.md
+templates/
+├── component-1/
+│   ├── template.yml
+│   └── docs.md
+└── component-2/
+    ├── template.yml
+    └── docs.md
+```
+
+For an example of a component `README.md`, see the [Deploy to AWS with GitLab CI/CD component's `README.md`](https://gitlab.com/components/aws/-/blob/main/README.md).
+
 ### Test the component
 
 Testing CI/CD components as part of the development workflow is strongly recommended