diff --git a/docs/content/community/_index.md b/docs/content/community/_index.md deleted file mode 100644 index 99ddef454..000000000 --- a/docs/content/community/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -type: docs -title: "Radius Community" -linkTitle: "Community" -description: "Information about the Radius community" -weight: 120 ---- \ No newline at end of file diff --git a/docs/content/community/media-coverage/index.md b/docs/content/community/media-coverage/index.md deleted file mode 100644 index c79b49dd8..000000000 --- a/docs/content/community/media-coverage/index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -type: docs -title: "Radius press coverage and media links" -linkTitle: "Press/media coverage" -description: "Learn about Radius through press articles, blog posts, presentation and other coverage of Radius" -weight: 200 ---- - -## Blog posts - -| Blog Title | Source | Date | -|------------|--------|------| -| [The Microsoft Azure Incubations Team launches Radius, a new open application platform for the cloud](https://azure.microsoft.com/en-us/blog/the-microsoft-azure-incubations-team-launches-radius-a-new-open-application-platform-for-the-cloud/) | Microsoft Azure Blog | Oct 18, 2023 | -| [Enabling developer collaboration with Radius](https://cloudblogs.microsoft.com/opensource/2023/10/18/enabling-developer-collaboration-with-radius/) | Microsoft Open Source Blog | Oct 18, 2023 | - -Ongoing blog posts can be found at [Radius Blog](https://blog.radapp.io). - -## Presentations - -| Video | Event | Date | -|-------|-------|------| -| [Brendan Burns and Mark Russinovich at Ignite about Radius](https://www.youtube.com/watch?v=gaG77PiYv5w&ab_channel=MicrosoftIgnite)| Microsoft Ignite | Nov 17, 2023 | -| [Introducing Radius - Open at Microsoft ](https://www.youtube.com/watch?v=mT_NWFnYn0A)| Open at Microsoft | Nov 7, 2023 | -| [Mark Russinovich at the Linux Foundation Member Summit](https://aka.ms/radius-lfms)|Linux Foundation Member Summit | Oct 24, 2023 | - -Want to give your own presentation? Check out the [Give a Radius Presentation]({{< ref presentations >}}) page. - -## Press articles - -| Article Title | Media Source | Date | -|---------------|--------------|------| -| [On Microsoft’s Radius, and building bridges between infra, dev and ops](https://gigaom.com/2024/01/05/on-microsofts-radius-and-building-bridges-between-infra-dev-and-ops/) | GigaOm | Jan 5, 2024 | -| [Microsoft Azure’s Cloud-Native Advances: Innovations and Future Outlook](https://www.newstrail.com/microsoft-azures/) | Newstrail | Nov 23, 2023 | -| [Microsoft Azure introduces Radius, an open-source development platform for multi-cloud computing](https://www.zdnet.com/article/microsoft-azure-introduces-radius-an-open-source-development-platform-for-multi-cloud-computing/)| ZDNET | Oct 27, 2023 | -| [Microsoft’s Radius and the future of cloud-native development](https://www.infoworld.com/article/3709448/microsofts-radius-and-the-future-of-cloud-native-development.html)| InfoWorld | Oct 26, 2023 | -| [Microsoft reimagines Modern Application Deployment With Radius Platform](https://www.forbes.com/sites/janakirammsv/2023/10/23/microsoft-reimagines-modern-application-deployment-with-radius-platform/?sh=6a78a37c76d7)| Forbes | Oct 23, 2023 | -| [ Microsoft launches Radius, an open-source application platform for the cloud-native era](https://techcrunch.com/2023/10/18/microsoft-launches-radius-an-open-source-application-platform-for-the-cloud/)| TechCrunch | Oct 18, 2023 | diff --git a/docs/content/community/overview/index.md b/docs/content/community/overview/index.md deleted file mode 100644 index fef8e1bfa..000000000 --- a/docs/content/community/overview/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -type: docs -title: "Radius Community" -linkTitle: "Overview" -description: "Information about the Radius community" -weight: 100 ---- - -Welcome to the Radius community! - -## Discussions - -The best way to interact with the community is via the Radius Discord server: - -{{< button link="https://aka.ms/radius/discord" text="Radius Discord" newtab="true" >}} - -## Community meetings - -Every month we host a community meeting to showcase new features, review upcoming milestones, and engage in a Q&A. Anyone from the Radius community can participate, present a topic, or host. All are welcome! For the meeting schedule, links, and more information, visit the Radius [community repo](https://github.com/radius-project/community#community-meetings). - -## How can I get involved? - -One of the easiest ways to contribute is to participate in discussions at community engagements or via the Discord server referenced above. We are always seeking feedback, especially for suggestions around improving the product and docs. - -If you are interested in contributing to the Radius project, please visit the [Contributing to Radius]({{< ref contributing >}}) page for more information. - -## Press and media coverage - -Visit the [press and media coverage docs]({{< ref media-coverage >}}) for a list of press articles, blog posts, presentations, and other coverage of Radius. diff --git a/docs/content/contributing/_index.md b/docs/content/contributing/_index.md index 9de6f74b3..e895c8119 100644 --- a/docs/content/contributing/_index.md +++ b/docs/content/contributing/_index.md @@ -2,6 +2,70 @@ type: docs title: "Contributing to Radius" linkTitle: "Contributing" -description: "Guides and requirements for contributing to Radius" +description: "Guides and requirements for contributing to and engaging with the Radius community" weight: 110 ---- \ No newline at end of file +aliases: + - "/community/" + - "/community/overview/" + - "/community/contributing/overview/" + - "/contributing/overview/" +--- + +Radius is built and maintained by an open community, and you're invited to contribute. Whether you write code, improve the docs, share a Recipe, file a bug, or answer questions, every contribution strengthens Radius. Use this page as your starting point. + +## Get started in three steps + +1. **Introduce yourself**: join the [Radius Discord](#stay-connected) to get help and connect with other contributors. +2. **Find something to work on**: browse the [good-first-issues](https://aka.ms/radius-first-issues) and `/assign` a beginner-friendly task to yourself. +3. **Make your change**: choose a [way to contribute](#ways-to-contribute) below, follow that repository's contribution guide, and open a pull request. + +Browse good-first-issues + +## Ways to contribute + +You don't need to write code to make an impact. Using Radius and sharing your experience is a valuable contribution in itself. Radius spans several repositories — choose the path that matches your interests and follow that repository's contribution guide to get started. + +{{< cardpane >}} + {{% card header="**🚀 Use Radius & share feedback**" footer="[**Get started with Radius →**]({{< ref quick-start >}})" %}} + Run Radius on your own apps, build a sample with Resource Types and Recipes, and [report bugs or request features](https://github.com/radius-project/radius/issues/new/choose). Real-world feedback shapes the roadmap. + {{% /card %}} + {{% card header="**💻 Contribute code**" footer="[**Radius contribution guide →**](https://github.com/radius-project/radius/blob/main/CONTRIBUTING.md)" %}} + Fix a bug or add a feature to the [`rad` CLI](https://github.com/radius-project/radius/blob/main/docs/contributing/contributing-code/contributing-code-cli/README.md), [control plane](https://github.com/radius-project/radius/blob/main/docs/contributing/contributing-code/contributing-code-control-plane/README.md), or other components in the main [radius-project/radius](https://github.com/radius-project/radius) repo, or help [review pull requests](https://github.com/radius-project/radius/pulls). + {{% /card %}} +{{< /cardpane >}} +{{< cardpane >}} + {{% card header="**🧩 Share Recipes & Resource Types**" footer="[**Resource Types contribution guide →**](https://github.com/radius-project/resource-types-contrib/tree/main/docs/contributing)" %}} + Add to the shared library of Radius Resource Types and Recipes in [radius-project/resource-types-contrib](https://github.com/radius-project/resource-types-contrib) that the whole community can reuse. + {{% /card %}} + {{% card header="**📝 Improve the docs**" footer="[**Docs contribution guide →**]({{< ref contributing-docs >}})" %}} + Fix typos, clarify guides, or write new content in [radius-project/docs](https://github.com/radius-project/docs). Documentation changes are one of the easiest ways to start contributing. + {{% /card %}} +{{< /cardpane >}} + +### Radius repositories + +All Radius source lives under the [radius-project](https://github.com/radius-project) organization on GitHub. The most common repositories to contribute to are: + +| Repository | Description | +|------------|-------------| +| [radius-project/radius](https://github.com/radius-project/radius) | Main repository with the source for the `rad` CLI, control plane, and other core Radius components | +| [radius-project/resource-types-contrib](https://github.com/radius-project/resource-types-contrib) | Shared library of Radius Resource Types and Recipes for Radius applications | +| [radius-project/docs](https://github.com/radius-project/docs) | Documentation for Radius (this site) | +| [radius-project/dashboard](https://github.com/radius-project/dashboard) | The frontend experience for Radius | +| [radius-project/blog](https://github.com/radius-project/blog) | Source for the Radius blog | +| [radius-project/samples](https://github.com/radius-project/samples) | Sample applications that demonstrate Radius | + +## Before your first pull request + +Review these requirements before you contribute: + +- **Read the Code of Conduct**: the Radius community follows the [CNCF Code of Conduct](https://github.com/radius-project/radius/blob/main/CODE_OF_CONDUCT.md). Be respectful and inclusive. +- **Sign your commits (DCO)**: every commit must be cryptographically signed. See the [contribution guide](https://github.com/radius-project/radius/blob/main/docs/contributing/contributing-code/contributing-code-first-commit/first-commit-06-creating-a-pr/index.md#signing-your-commits) for details. +- **Follow the repository's contribution guide**: each repository has its own setup and workflow instructions. Start there. +- **Ask for help when you need it**: reach out on [Discord](#stay-connected) or comment on the issue you're working on. + +## Stay connected + +Connect with the community on the Radius Discord server: + +{{< button link="https://aka.ms/radius/discord" text="Join the Radius Discord" newtab="true" >}} diff --git a/docs/content/contributing/advocacy/index.md b/docs/content/contributing/advocacy/index.md new file mode 100644 index 000000000..2bb81cbc6 --- /dev/null +++ b/docs/content/contributing/advocacy/index.md @@ -0,0 +1,40 @@ +--- +type: docs +title: "Spread the word" +linkTitle: "Spread the word" +description: "Give presentations, write about Radius, and share it with your community" +weight: 300 +aliases: + - "/community/presentations/" + - "/contributing/presentations/" + - "/community/media-coverage/" + - "/contributing/media-coverage/" +--- + +Help spread the word about Radius! Whether you're giving a talk, writing a blog post, sharing on social media, or introducing Radius to your team, this page has the resources to help. + +## Give a presentation + +We welcome community members giving presentations on Radius and spreading the word about all its features. + +1. **Download the slide template.** Start from the template PowerPoint, which contains the slides you need to give a Radius presentation. + + Download the Radius PowerPoint template + +1. **Gather supporting assets.** Browse the [presentation pack directory](https://github.com/radius-project/docs/tree/{{< param github_branch >}}/presentation-pack) for diagrams and images you can reuse. +1. **Prepare your pitch.** Review the [concepts]({{< ref concepts >}}) so you can explain what Radius is and why it matters. +1. **Prepare a demo.** Use the [tutorials]({{< ref tutorials >}}) and the [samples repository](https://github.com/radius-project/samples) to demonstrate Radius in action. + +## Write about Radius + +Blog posts and articles are a great way to share how you use Radius. + +- Write about your experience, a walkthrough, or a use case — and let us know on [Discord](https://aka.ms/radius/discord) so we can help amplify it. +- Read existing posts for ideas and style at the [Radius Blog](https://blog.radapp.io). + +## Share online + +- Star and share the [radius-project](https://github.com/radius-project) repositories on GitHub. +- Post about Radius on social media and in your communities. +- Introduce Radius to your team and point them to the [getting started guide]({{< ref quick-start >}}). +- Join the conversation on [Discord](https://aka.ms/radius/discord). diff --git a/docs/content/contributing/docs/contributing-docs/diataxis.png b/docs/content/contributing/contributing-docs/diataxis.png similarity index 100% rename from docs/content/contributing/docs/contributing-docs/diataxis.png rename to docs/content/contributing/contributing-docs/diataxis.png diff --git a/docs/content/contributing/docs/contributing-docs/index.md b/docs/content/contributing/contributing-docs/index.md similarity index 68% rename from docs/content/contributing/docs/contributing-docs/index.md rename to docs/content/contributing/contributing-docs/index.md index d9472c895..cde461d18 100644 --- a/docs/content/contributing/docs/contributing-docs/index.md +++ b/docs/content/contributing/contributing-docs/index.md @@ -3,12 +3,10 @@ type: docs title: "How-To: Contribute to the Radius documentation" linkTitle: "Contribute to docs" description: "How to contribute to the Radius documentation" -weight: 100 -aliases : ["/community/contributing/docs/"] +weight: 200 +aliases: ["/community/contributing/docs/", "/contributing/docs/contributing-docs/", "/community/maintainers/docs-maintainers/", "/contributing/docs/maintainers-docs/", "/contributing/maintainers-docs/"] --- -The Radius docs are built on [Hugo](https://gohugo.io) with the [Docsy](https://docsy.dev) theme. GitHub Actions are used to build and deploy the docs upon each PR. - Radius uses the [Diátaxis framework](https://diataxis.fr/) for its documentation: {{< image src="diataxis.png" alt="Diagram showing the diataxis framework" width=800px >}} @@ -17,29 +15,30 @@ Follow the guidance on this page to learn how to get started, how to contribute, ## Setup your docs environment -### GitHub Codespace (easiest) +{{< tabs "GitHub Codespace" "Local machine" >}} -It's easy to get up and running with a GitHub Codespace. This will give you a fully configured environment with all the tools you need to build the docs, all in your browser. +{{% codetab %}} +The easiest way to get up and running is with a GitHub Codespace. This gives you a fully configured environment with all the tools you need to build the docs, all in your browser. {{< button link="https://github.com/codespaces/new?hide_repo_select=true&repo=421982809" text="Create codespace" >}} -> Note the `postCreateCommand` may take up to 3 minutes to complete after the codespace is created to complete. +> Note the `postCreateCommand` may take up to 3 minutes to complete after the codespace is created. 1. Start Codespace 1. Wait for `postCreateCommand` to complete 1. Run `cd docs` to enter the hugo site directory 1. Run `hugo server` to start the local server 1. Click on the link in the terminal to open the docs in your browser +{{% /codetab %}} -### Local machine - -### Pre-requisites +{{% codetab %}} +**Pre-requisites** - [Hugo extended version](https://gohugo.io/getting-started/installing) - [Node.js](https://nodejs.org/en/) - [git](https://git-scm.com/downloads) -### Environment setup +**Environment setup** 1. Ensure pre-requisites are installed 1. Clone this repository and the radius repository @@ -78,7 +77,7 @@ It's easy to get up and running with a GitHub Codespace. This will give you a fu cd .. ``` -### Run local server +**Run local server** 1. Make sure you're still in the `docs` directory 1. Run @@ -88,6 +87,9 @@ It's easy to get up and running with a GitHub Codespace. This will give you a fu ``` 1. Navigate to `http://localhost:1313/` +{{% /codetab %}} + +{{< /tabs >}} ## Developer Certificate of Origin @@ -111,52 +113,19 @@ Visual Studio Code has a setting, `git.alwaysSignOff` to automatically add a Sig ## Types of docs -There are 5 types of docs in Radius: - -1. **Concept** - A concept doc is a high-level overview of the project or an area of the project. -1. **Overview** - A overview page documents a specific feature or capability of the project, with information on what the feature is and additional context and links on how to use it. -1. **How-To** - A how-to guide is a step-by-step guide to help the reader achieve a specific task. It assumes the reader has a basic understanding of the project and its concepts. For more information on how-to guides, see [Diátaxis](https://diataxis.fr/how-to-guides/). -1. **Reference** - A reference doc is a detailed description of a specific feature or capability of the project. It assumes the reader has a basic understanding of the project and its concepts. For more information on reference docs, see [Diátaxis](https://diataxis.fr/reference/). - -Overall: - -- Avoid creating new sections where possible, there is a good chance a proper place in the docs hierarchy already exists. -- Make sure to include a complete [Hugo front-matter](#front-matter). -- Determine the [type of doc](#types-of-docs) you are contributing - -### Concept docs - -Visit [Diátaxis](https://diataxis.fr/explanation/) for more information on explanatory documentation that helps the user understand the project or a specific area of the project. - -- Ensure the reader can understand why they should care about the project or the concept. What problems does it help them solve? -- Provide a link to the overview page of the feature that justifies the concept(s) -- Provide the reader with related links if needed (this can be other concepts, overviews, how-to guides, or references) -- Set the `category` as `Concept` in [Hugo front-matter](#front-matter). - -### Overview docs - -Visit [Diátaxis](https://diataxis.fr/explanation/) for more information on explanatory documentation that helps the user understand the project or a specific area of the project. - -- Ensure the reader can understand why they should care about the feature and what it enables them to do. -- If applicable, ensure the doc references the reference spec document. -- If applicable, ensure the doc is consistent with any related concepts or specs in terms of names, parameters, and terminology. Update both the concept, spec, and the doc as needed. Avoid repeating the spec. The idea is to give the reader more information and background on the capability so that they can try this out. -- Provide the reader with related links if needed (this can be other concepts, overviews, how-to guides, or references) -- Set the `category` as `Overview` in [Hugo front-matter](#front-matter). - -### How-To guides - -Visit [Diátaxis](https://diataxis.fr/how-to-guides/) for more information on how-to documentation that helps the user accomplish a specific task. - -- Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This includes OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT, etc.), or programming language. If instructions vary between operating systems, provide guidance for all. -- Include code/sample/config snippets that can be easily copied and pasted. -- Provide the reader with related links if needed (this can be other concepts, overviews, how-to guides, or references) -- Set the `category` as `How To` in [Hugo front-matter](#front-matter). +Radius follows the [Diátaxis framework](https://diataxis.fr/). Pick the type that matches your goal — the docs are organized by type, so place your page in the matching section: -### Reference docs +- **Concept** — explain what something is and why it matters, so the reader understands the problem it solves. +- **Tutorial** — teach a newcomer by guiding them through a complete, hands-on lesson from start to finish. +- **How-To** — walk a reader who already knows the basics through completing a specific task, step by step. +- **Reference** — describe the details of a feature precisely; auto-generate from source code where possible. +- **Schema** — document the schema of a resource type or API, typically generated from the source definition. -Visit [Diátaxis](https://diataxis.fr/reference/) for more information on reference documentation that helps the user understand the details of a specific feature or capability of the project. +Whatever you write: -Reference docs should be auto-generated from source-code whenever possible. Please contact the maintainers if you need to add a new reference doc, or open an Issue to discuss. +- Reuse an existing section instead of creating a new one where possible — there's a good chance the right place already exists. +- Write for a new-developer audience: keep steps explicit, copy-pasteable, and environment-agnostic unless the doc is specific to one environment. +- Link to related concepts, overviews, how-to guides, and references. ## Writing styles and tips @@ -175,7 +144,7 @@ These conventions should be followed throughout all Radius documentation to ensu ### Spelling -The docs pipeline uses [cspell](https://cspell.org/) to check for spelling mistakes. The configuration lives in `.github/configs/.cspell.yml` and is kept in sync with the [radius-project/radius](https://github.com/radius-project/radius) repository so spell-checking behaves the same across Radius repos. If you need to add a new custom word to the allow-list, append it to `.cspellignore` at the repository root (keep the list sorted, one word per line). +The docs pipeline uses [cspell](https://cspell.org/) to check for spelling mistakes. The configuration lives in `.github/configs/.cspell.yml` and is synced from the [radius-project/.github](https://github.com/radius-project/.github) repository so spell-checking behaves the same across Radius repos. If you need to add a new custom word to the allow-list, append it to `.cspellignore` at the repository root (keep the list sorted, one word per line). To run the spell checker locally: @@ -213,7 +182,6 @@ title: "TITLE FOR THE PAGE" linkTitle: "SHORT TITLE FOR THE NAV BAR" weight: (number) description: "1+ SENTENCES DESCRIBING THE ARTICLE" -categories: "TYPE OF THE DOCUMENT" tags: "METADATA ON THE DOCUMENT" --- ``` @@ -223,12 +191,11 @@ tags: "METADATA ON THE DOCUMENT" ```yaml --- type: docs -title: "Service invocation overview" +title: "Recipes overview" linkTitle: "Overview" weight: 10 -description: "A quick overview of Dapr service invocation and how to use it to invoke services within your application" -categories: "Concept" -tags: "Dapr" +description: "A quick overview of Radius Recipes and how to use them to deploy infrastructure for your application" +tags: "Recipes" --- ``` @@ -237,22 +204,15 @@ tags: "Dapr" > - Index file weights follow the parent directory's ordering. > - For the first page in a new directory, reset the counter and set the weight to be an order of magnitude greater. -Front-matter should be completed with all fields including type, title, linkTitle, weight, description, categories and tags. +Front-matter should be completed with all fields including type, title, linkTitle, weight, description, and tags. - `title` should be 1 sentence, with no period at the end - `linkTitle` should be 1-3 words, with the exception of How-to at the front. - `description` should be 1-2 sentences on what the reader will learn, accomplish, or do in this doc. -- `categories` should be one of the following: - - Concept - - Overview - - Tutorial - - How-To - - Reference - - Schema - `tags` should be a comma-separated list of metadata tags. -As per the [styling conventions](#styling-conventions), titles should only capitalize the first word and proper nouns, with the exception of "How-To:" - - "Getting started with Dapr service invocation" +As per the [styling conventions](#style-and-tone), titles should only capitalize the first word and proper nouns, with the exception of "How-To:" + - "Getting started with Radius Recipes" - "How-To: Setup a local Redis instance" ### Referencing other pages @@ -350,7 +310,7 @@ The shortcode below and code sample: ```bicep // in snippets/mysample.bicep -resource app 'radius.dev/Application@v1alpha1' = { +resource app 'radius.dev/Application@v1alpha3' = { name: 'storefront-app' //SAMPLE @@ -391,7 +351,7 @@ Will result in the following output: The markdown spec used by Docsy and Hugo does not give an option to resize images using markdown notation. Instead, raw HTML is used. -Begin by placing images under `/daprdocs/static/images` with the naming convention of `[page-name]-[image-name].[png|jpg|svg]`. +Begin by placing images under `/docs/static/images` with the naming convention of `[page-name]-[image-name].[png|jpg|svg]`. Then link to the image using: @@ -406,7 +366,7 @@ Then link to the image using: This HTML will display the `radius-overview.png` image on the `overview.md` page: ```md -{{}} +{{}} ``` ### Alerts @@ -478,19 +438,19 @@ All content you author will be rendered to Markdown, so you can include images, {{% codetab %}} ```powershell -powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex" +iwr -useb "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.ps1" | iex ``` {{% /codetab %}} {{% codetab %}} ```bash -wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash +wget -q "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" -O - | /bin/bash ``` {{% /codetab %}} {{% codetab %}} ```bash -brew install dapr/tap/dapr-cli +curl -fsSL "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" | /bin/bash ``` {{% /codetab %}} @@ -504,7 +464,7 @@ This example will render to this: {{% codetab %}} ```powershell -powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex" +iwr -useb "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.ps1" | iex ``` {{% /codetab %}} @@ -512,7 +472,7 @@ powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master {{% codetab %}} ```bash -wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash +wget -q "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" -O - | /bin/bash ``` {{% /codetab %}} @@ -520,7 +480,7 @@ wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O {{% codetab %}} ```bash -brew install dapr/tap/dapr-cli +curl -fsSL "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" | /bin/bash ``` {{% /codetab %}} @@ -587,17 +547,11 @@ You can customize the colors using the Bootstrap colors: {{}} {{}} {{}} -{{}} -{{}} -{{}} ``` {{< button text="My Button" link="https://example.com" color="primary" >}} {{< button text="My Button" link="https://example.com" color="secondary" >}} {{< button text="My Button" link="https://example.com" color="success" >}} -{{< button text="My Button" link="https://example.com" color="danger" >}} -{{< button text="My Button" link="https://example.com" color="warning" >}} -{{< button text="My Button" link="https://example.com" color="info" >}} #### Inline buttons @@ -611,21 +565,54 @@ By default, buttons are padded with new lines below the button. To remove these {{< button text="Previous" link="https://example.com" newline="false" >}} {{< button text="Next" link="https://example.com" >}} -#### Categorize content +## Maintaining the docs -You can use the `categorizeby` shortcode to pull and organize content by either categories and tags. This is useful when you want to categorize content by tags and the type of the document +This section covers routine Radius docs maintainer and approver responsibilities. To perform these tasks, you need either approver or maintainer status in the [`radius-project/docs`](https://github.com/radius-project/docs) repo. -```text -{{ categorizeby category="How-To" tag= "containers" }} -``` +### Branch guidance -This categorizes and lists all the docs that has both "How-To" as the category and "container" as the tag. +The Radius docs handles branching differently than most code repositories. Instead of a `main` branch, every branch is labeled to match the major and minor version of a runtime release, plus an `edge` branch for in-flight work. For example, the `v1.0` branch contains the docs for the `v1.0` release. The `edge` branch contains the latest in-flight work. -```text -{{ categorizeby category="How-To" }} -``` +### Managing content between branches + +As a docs approver or maintainer, you need to perform routine **upmerges** to keep the pre-release `edge` branch aligned with updates to the current release branch. It is recommended to upmerge the current branch into the pre-release branch on a weekly basis. + +For the following steps, treat `v1.0` as the current release and `edge` as the pre-release branch. + +1. Open Visual Studio Code to the Radius docs repo. +1. From your local repo, switch to the latest branch (`v1.0`) and synchronize changes: + + ```bash + git pull upstream v1.0 + git push origin v1.0 + ``` + +1. Switch to the upcoming branch (`edge`) and synchronize changes: + + ```bash + git pull upstream edge + git push origin edge + ``` + +1. Create a new branch from `edge`: + + ```bash + git checkout -b upmerge_MM-DD + ``` + +1. Open a terminal and stage a merge from the latest release into the upmerge branch: + + ```bash + git merge --no-ff --no-commit v1.0 + ``` -This categorizes and lists all the docs that are How-To by the available tags. +1. Make sure included files look accurate. Inspect any merge conflicts in VS Code. Remove configuration changes or version information that does not need to be merged. Examples of files that usually shouldn't be merged: + - docs/config.toml + - docs/layouts/partials/hooks/body-end.html + - docsy sub-module +1. Commit the staged changes and push to the upmerge branch (`upmerge_MM-DD`). +1. Open a PR from the upmerge branch to the upcoming release branch (`edge`). +1. Review the PR and double check that no unintended changes were pushed to the upmerge branch. ### References diff --git a/docs/content/contributing/docs/_index.md b/docs/content/contributing/docs/_index.md deleted file mode 100644 index 578d023bf..000000000 --- a/docs/content/contributing/docs/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -type: docs -title: "Radius Docs" -linkTitle: "Docs" -description: "Learn how to contribute and maintain the Radius documentation" -weight: 300 ---- \ No newline at end of file diff --git a/docs/content/contributing/docs/architecture.png b/docs/content/contributing/docs/architecture.png deleted file mode 100644 index 93b18dccd..000000000 Binary files a/docs/content/contributing/docs/architecture.png and /dev/null differ diff --git a/docs/content/contributing/docs/maintainers-docs/index.md b/docs/content/contributing/docs/maintainers-docs/index.md deleted file mode 100644 index 6067d197b..000000000 --- a/docs/content/contributing/docs/maintainers-docs/index.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -type: docs -title: "How-To: Maintain the Radius docs" -linkTitle: "Maintain docs" -weight: 200 -description: "Learn about the Radius docs maintenance process" -aliases : ["/community/maintainers/docs-maintainers/"] ---- - -In this guide, you’ll learn how to perform routine Radius docs maintainer and approver responsibilities. In order to successfully accomplish these tasks, you need either approver or maintainer status in the [`radius-project/docs`](https://github.com/radius-project/docs) repo. - -To learn how to contribute to Radius docs, review the [Contributor guide]({{< ref contributing-docs >}}). - -## Branch guidance - -The Radius docs handles branching differently than most code repositories. Instead of a `main` branch, every branch is labeled to match the major and minor version of a runtime release, plus an `edge` branch for in-flight work. For example, the `v1.0` branch contains the docs for the `v1.0` release. The `edge` branch contains the latest in-flight work. - -### Managing content between branches - -As a docs approver or maintainer, you need to perform routine **upmerges** to keep the pre-release `edge` branch aligned with updates to the current release branch. It is recommended to upmerge the current branch into the pre-release branch on a weekly basis. - -For the following steps, treat `v1.0` as the current release and `edge` as the pre-release branch. - -1. Open Visual Studio Code to the Radius docs repo. -1. From your local repo, switch to the latest branch (`v1.0`) and synchronize changes: - - ```bash - git pull upstream v1.0 - git push origin v1.0 - ``` - -1. Switch to the upcoming branch (`edge`) and synchronize changes: - - ```bash - git pull upstream edge - git push origin edge - ``` - -1. Create a new branch from `edge`: - - ```bash - git checkout -b upmerge_MM-DD - ``` - -1. Open a terminal and stage a merge from the latest release into the upmerge branch: - - ```bash - git merge --no-ff --no-commit v1.0 - ``` - -1. Make sure included files look accurate. Inspect any merge conflicts in VS Code. Remove configuration changes or version information that does not need to be merged. Examples of files that usually shouldn't be merged: - - docs/config.toml - - docs/layouts/partials/hooks/body-end.html - - docsy sub-module -1. Commit the staged changes and push to the upmerge branch (`upmerge_MM-DD`). -1. Open a PR from the upmerge branch to the upcoming release branch (`edge`). -1. Review the PR and double check that no unintended changes were pushed to the upmerge branch. diff --git a/docs/content/contributing/overview/index.md b/docs/content/contributing/overview/index.md deleted file mode 100644 index 1b13ccfa3..000000000 --- a/docs/content/contributing/overview/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -type: docs -title: "Overview: Contributing to Radius" -linkTitle: "Overview" -description: "Guides and requirements for contributing to Radius" -weight: 100 -aliases: ["/community/contributing/overview"] ---- - -We welcome contributions to Radius! Contributions can come in different ways such as engaging with the community, contributing code, or improving the documentation. This page provides an overview of the different ways you can contribute to Radius. - -## Community - -Check out the [Radius Community]({{< ref community >}}) page to learn about the different ways you can engage with the Radius community. - -## GitHub - -If you would like to file Issues, access the source code, or use Codespaces please visit the [Radius GitHub repo](https://github.com/radius-project). - -### good-first-issues - -To quickly get started with contributing to code on Radius, here are some identified [good-first-issues](https://aka.ms/radius-first-issues) that you can `/assign` to yourself and start contributing. - -good-first-issues - -### Contributing to Radius - -Check out the following table to learn where and how you can contribute: - -| Repository | Description | Contribution guides | -|------------|-------------|---------------------| -| **Resource Types and Recipes** | Shared library of Radius Resource Types and Recipes for Radius applications | [radius-project/resource-types-contrib](https://github.com/radius-project/resource-types-contrib/tree/main/docs/contributing) | -| **Radius** | Main repository that contains source code for [`rad` CLI](https://github.com/radius-project/radius/blob/main/docs/contributing/contributing-code/contributing-code-cli/README.md), [control plane](https://github.com/radius-project/radius/blob/main/docs/contributing/contributing-code/contributing-code-control-plane/README.md) and other components of Radius | [radius-project/radius](https://github.com/radius-project/radius/blob/main/CONTRIBUTING.md)| -| **Docs** | Documentation for Radius | [radius-project/docs]({{< ref contributing-docs>}})| -| **Dashboard** | The frontend experience for Radius |[radius-project/dashboard](https://github.com/radius-project/dashboard/blob/main/CONTRIBUTING.md) | diff --git a/docs/content/contributing/presentations/index.md b/docs/content/contributing/presentations/index.md deleted file mode 100644 index f2f3c830c..000000000 --- a/docs/content/contributing/presentations/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -type: docs -title: "Give a Radius presentation" -linkTitle: "Presentations" -description: "Learn how to give a Radius presentation, with downloadable slides and assets" -weight: 400 -aliases : ["/community/presentations/"] ---- - -We welcome community members giving presentations on Radius and spreading the word about all the awesome Radius features! - -## Slides - -We offer a template PowerPoint file to get started: - -Download the Radius PowerPoint template - -## Giving a Radius presentation - -### Presentation pack - -1. Begin by downloading the [Radius Presentation Deck](https://github.com/radius-project/docs/raw/{{< param github_branch >}}/presentation-pack/Radius.potx). This contains slides needed to give a Radius presentation. -1. Refer to the Radius [presentation pack directory](https://github.com/radius-project/docs/tree/{{< param github_branch >}}/presentation-pack) for any diagrams or images you need to create. - -### Preparing the elevator pitch for Radius - -1. Refer to the [Radius press coverage and media links]({{< ref media-coverage >}}) page for a list of previous presentations, articles, and videos. -1. Next, review the docs to make sure you understand the [concepts]({{< ref concepts >}}). - -### Preparing the demo - -1. Use the Radius [tutorial]({{< ref tutorial >}}) and [samples repo](https://github.com/radius-project/samples) to show demos of how to use Radius. - -## Other resources - -- [Radius Homepage​](https://radapp.io)​ is starting point for all things Radius. -- To view code and file issues​, visit the [radius-project](https://github.com/radius-project) in GitHub. -- To read the latest blog posts on Radius​, visit [Blog](https://blog.radapp.io). ​ -- Visit the [feature roadmap for Radius](https://aka.ms/radius-roadmap) for updates on what's coming next.