Add a project contributor guide

Documentation of how to contribute to the project gives everyone the opportunity to participate, while also reducing
maintenance effort and increasing quality of contributions.

This guide documents the various ways of contributing to the project.

It takes advantage of GitHub's "contributing guidelines" feature to increase the visibility of the information to
prospective contributors. The promoted "CONTRIBUTING.md" file is used as an entry point to the guide, with links from
there leading to dedicated guides for each specific type of contribution. In this way, the contributor is only presented
with relevant information, improving the approachability and readability of the content.

Author: per1234

README.md

@@ -15,14 +15,8 @@ This repository is used for collaborative development of the assets of the [Ardu
 
 The source content and metadata of the assets is stored in the files in this repository. There is additional documentation about the assets in their individual folders.
 
-The development is done via a formal process that allows all interested parties the opportunity to participate in an efficient manner:
+## How to Contribute
 
-1. Create [a branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-branches) to contain your proposed changes.
-1. Make your proposed changes to the appropriate file.
-1. [Commit](https://git-scm.com/docs/git-commit) the change to the repository.
-1. Submit a [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) (PR) from your branch to the `main` branch.
-1. Some automated checks will now run on the pull request to make sure there are not any typos, broken links, or style issues. If the check failure doesn't seem correct, feel free to request `@per1234` to investigate.
-1. All interested parties will now have the opportunity to [review the pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews). They can request changes, make general comments and discussion, or approve the pull request.
-1. If any changes have been requested by reviewers, the pull request author can make changes to the pull request's branch and commit them. These commits will automatically be added to the pull request.
-1. Once the pull request has been approved, it is [merged](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request) into the `main` branch.
-1. The content is published to the Arduino Forum.
+Contributions are welcome!
+
+Please see the [**Contributor Guide**](docs/CONTRIBUTING.md) for information.

docs/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/general/CONTRIBUTING.md -->
+
+# Contributor Guide
+
+Thanks for your interest in contributing to this project!
+
+There are several ways you can get involved:
+
+| Type of contribution                       | Contribution method                                                              |
+| ------------------------------------------ | -------------------------------------------------------------------------------- |
+| - Support<br/>- Question<br/>- Discussion  | Post on the [**Arduino Forum**][forum]                                           |
+| - Defect report<br/>- Enhancement proposal | Issue report (see the guide [**here**][issues])                                  |
+| - Correction<br/>- Enhancement             | Pull request (see the guide [**here**][prs])                                     |
+| Monetary                                   | - [Donate][donate]<br/>- [Sponsor][sponsor]<br/>- [Buy official products][store] |
+
+[forum]: https://forum.arduino.cc
+[issues]: contributor-guide/issues.md#issue-report-guide
+[prs]: contributor-guide/pull-requests.md#pull-request-guide
+[donate]: https://www.arduino.cc/en/donate/
+[sponsor]: https://github.com/sponsors/arduino
+[store]: https://store.arduino.cc
+
+## Resources
+
+- [**Development Guide**](development.md#development-guide)

docs/README.md

@@ -0,0 +1,5 @@
+# Project Documentation
+
+This folder contains the documentation for contributing to this project.
+
+See the [**Contributor Guide**](CONTRIBUTING.md).

docs/contributor-guide/assets/checks.png

@@ -0,0 +1,28 @@
+<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/general/contributor-guide/issues.md -->
+
+# Issue Report Guide
+
+---
+
+❗ Do you need help or have a question about using this project? Support requests should be made to the [Arduino Forum](https://forum.arduino.cc).
+
+---
+
+High quality defect reports and enhancement proposals are valuable contributions to this project. These can be made by submitting an issue report to the project's GitHub repository:
+
+https://github.com/per1234/forum-assets/issues/new/choose
+
+## Before Reporting an Issue
+
+Search [existing pull requests and issues](https://github.com/per1234/forum-assets/issues?q=) to see if it was already reported.<br />
+
+If you have additional information to provide about an existing issue, please comment there instead of creating a duplicate. You can use [GitHub's "Reactions" feature](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) if you only want to express support 👍.
+
+## Qualities of an Excellent Report
+
+- Concise and descriptive issue title.<br />
+  Vague titles make it difficult to decipher the purpose of the issue when looking through the list of reports, which might result in your issue not being given proper attention.
+- Describe the issue and what behavior you were expecting.
+- Be responsive.<br />
+  We may need you to provide additional information in order to investigate and resolve the issue.<br />
+  Make sure your GitHub account is configured so that you will receive notifications of responses to your issue report.

docs/contributor-guide/issues.md

@@ -0,0 +1,73 @@
+# Pull Request Guide
+
+The development is done via a formal process that allows all interested parties the opportunity to participate in an efficient manner:
+
+## 1. Fork
+
+Forking a GitHub repository creates a copy of it under your account. You will stage contributions in your fork of this project.
+
+[More information about forking repositories](https://docs.github.com/get-started/quickstart/fork-a-repo)
+
+## 2. Branch
+
+Create a branch in your fork to contain the changes for your contribution.
+
+---
+
+**ⓘ** You must make a separate branch in your fork for each pull request you submit.
+
+---
+
+[More information about branches](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches)
+
+## 3. Make your changes
+
+See [the development guide](../development.md#development-guide) for more information.
+
+## 4. Commit
+
+Once the work on your change is complete, add it to the revision history of the Git repository by making a commit.
+
+[More information about commits](https://git-scm.com/docs/git-commit)
+
+## 5. Pull request
+
+A pull request (PR) is a proposal to make a change in a repository. The repository maintainer is able to accept the changes you propose in a pull request by simply clicking a button.
+
+[More information about pull requests](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
+
+## 6. Resolve CI failures
+
+Relevant checks will run automatically once you have submitted the pull request. Once these checks are finished, you can see a summary of the results near the bottom of the pull request page:
+
+![checks](assets/checks.png)
+
+Failed checks will be indicated with an ❌. If any checks failed, please fix whatever caused it to fail. Click the "**Details**" link to the right of the check name to open the logs, which provide details about the failure.
+
+---
+
+**ⓘ** In some rare cases, a CI failure may be unrelated to the changes made in your pull request. So if the information in the logs doesn't seem relevant, please comment on the pull request to ask a maintainer to take a look.
+
+---
+
+## 7. Review
+
+All interested parties will now have the opportunity to review the pull request. They can request changes, make general comments and discussion, or approve the pull request.
+
+[More information about pull request reviews](https://docs.github.com/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews)
+
+## 8. Resolve change requests
+
+To act on general review suggestions, you can add commits to the branch you submitted the pull request from, which will automatically be added to the pull request. Don't create a new pull request to act on review suggestions; update the existing pull request.
+
+Reviewers may suggest specific changes, which can be applied by [clicking the <kbd>**Commit suggestion**</kbd> button](https://docs.github.com/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request#applying-suggested-changes).
+
+## 9. Merge
+
+One of the repository maintainers can now choose to accept your proposed change. Once the pull request is [merged](https://docs.github.com/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request), you can delete the branch you created in your fork for the pull request and delete the fork as well if you like.
+
+## 10. Publish
+
+If the contribution modified content that is published on the Arduino Forum, a maintainer will publish the updated content.
+
+Thanks so much for your contribution!

docs/contributor-guide/pull-requests.md

@@ -0,0 +1,135 @@
+# Development Guide
+
+## Add or Remove a Pinned Topic
+
+"Pinned" topics are always shown at the top of the category's listing.
+
+1. Find the category for the pinned topic under [the `content/categories` folder](../content/categories).
+1. Open the `_pins.md` file you find there.
+1. Add or remove the URL of the topic to the list.
+1. Save the file.
+1. Submit a [pull request](contributor-guide/pull-requests.md) for the change.
+
+## Change the Description of a Topic
+
+The content of the "**About the \_\_\_\_\_ category**" topics is used as the category description in the category listings. This description helps the users to understand whether the category is the appropriate place for a topic they are creating.
+
+1. Find the category for the pinned topic under [the `content/categories` folder](../content/categories).
+1. Open the `_topics` subfolder.
+1. Find the subfolder for the category's "**About the \_\_\_\_\_ category**" topic is used as the category description in the category listings.
+1. Open the `1.md` file from the subfolder.
+1. Make the desired changes to the content of the file.
+1. Save the file.
+1. Submit a [pull request](contributor-guide/pull-requests.md) for the change.
+
+## Add or Edit a Discourse Template
+
+["Discourse Templates"](https://meta.discourse.org/t/discourse-templates/229250) provide standardized reusable content for common posts.
+
+Templates are used in posts by clicking the **⚙** icon on the post composer toolbar and then selecting "**Insert template**" from the menu.
+
+---
+
+❗ The Discourse Templates feature is only available for staff members (moderators and administrators).
+
+---
+
+### Add Template
+
+The [existing templates](../content/categories/templates/_topics) will serve as a reference for the addition of new template source content.
+
+1. Open [the `content/categories/templates/_topics` folder](../content/categories/templates/_topics).
+1. Create a folder named according to the template title.
+1. Create a file named `README.md`.
+1. Add the template title as an H1 [heading](https://www.markdownguide.org/basic-syntax/#headings). <br />
+   For example:
+   ```markdown
+   # Some Amazing Template
+   ```
+   **ⓘ** This will be the title shown in the "**Insert template**" interface on the forum.
+1. Save the file.
+1. Create a file named `1.md`.
+1. Add the template text to the file.
+1. Save the file.
+1. Submit a [pull request](contributor-guide/pull-requests.md) for the change.
+
+### Edit Template
+
+1. Open [the `content/categories/templates/_topics` folder](../content/categories/templates/_topics).
+1. Find the folder of the template you want to edit.
+1. If you want to edit the template title, open the `README.md` file and edit the text of the H1 [heading](https://www.markdownguide.org/basic-syntax/#headings). <br />
+   For example:
+   ```markdown
+   # Some Amazing Template
+   ```
+1. If you want to edit the template text, open the `1.md` file and edit the text.
+1. Save the file.
+1. Submit a [pull request](contributor-guide/pull-requests.md) for the change.
+
+## Add an Asset Topic
+
+New asset topics can be added to the repository to enable collaborative development and maintenance of its content.
+
+---
+
+❗ In order to allow maintenance to continue in perpetuity, ownership of all posts maintained in this repository must be transferred to the forum's `@system` user.
+
+---
+
+1. Find the category for the topic under [the `content/categories` folder](../content/categories).
+1. Open the `_topics` subfolder.
+1. Create a folder named according to the topic title.
+1. Create a file named `README.md`.
+1. Add the topic title as an H1 [heading](https://www.markdownguide.org/basic-syntax/#headings). <br />
+   For example:
+   ```markdown
+   # Some Valuable Topic
+   ```
+1. If the topic is already published on Arduino Forum, add the URL under a `## Published At` heading.
+   For example:
+   ```markdown
+   ## Published At
+
+   https://forum.arduino.cc/t/some-valuable-topic/1234
+   ```
+1. Save the file.
+1. Create a file named `1.md`.
+1. Add the post text to the file.
+1. Save the file.
+1. Repeat steps (8)-(10) for any additional asset posts in the topic (naming the file according to the post number).
+1. Submit a [pull request](contributor-guide/pull-requests.md) for the change.
+
+## Validating Your Work
+
+When you submit a pull request to the repository, automated checks will run to detect any problems or inconsistencies. It is possible to also run these checks locally during the development if you like.
+
+### Prerequisites
+
+The following development tools must be available in your local environment:
+
+- [**Task**](https://taskfile.dev/installation/)
+- [**Node.js**](https://nodejs.dev/en/download/)
+- [**Python**](https://www.python.org/downloads/)
+- [**Poetry**](https://python-poetry.org/docs/#installation)
+
+### Running Checks
+
+Execute the following command from the root of the repository to run all available checks:
+
+```text
+task check
+```
+
+If you prefer to run specific checks individually, run the `task` command to get a list of available tasks.
+
+### Automatic Corrections
+
+Tools are provided to automatically bring the project into compliance with some of the required checks.
+
+Execute the following command from the root of the repository to run all available corrections:
+
+```text
+task fix
+```
+
+If you prefer to run specific correction operations individually, run the `task` command to get a list of available tasks.