Merge pull request #20 from f-hollow/docs/add_contribution_guide

Docs/add contribution guide

README.md

@@ -1 +1,16 @@
-# developer-portal
+# Developer Portal
+
+This project stores the files for the [Espressif Developer Portal][] website. GitHub Actions statically generate the website using Hugo and pushes it to a web server for online hosting.
+
+[Espressif Developer Portal]: https://developer.espressif.com/
+
+If you want to contribute to this project, it would be nice to see the rendered version. The website can be easily rendered on your local machine using the following steps:
+
+1. Clone this repository using `git clone --recursive`.
+2. Install Hugo following the [instructions](https://gohugo.io/installation/).
+3. In the project folder, run `hugo server` and open the provided local web address, usually http://localhost:1313/.
+
+See also the Contribution Guide articles:
+
+- [Content contribution workflow](./content/pages/contribution_guide/content-contrib-workflow/index.md)
+- [Content writing workflow](./content/pages/contribution_guide/content-writing-workflow/index.md)

config/_default/menus.en.toml

@@ -1,7 +1,7 @@
 # -- Main Menu --
 # The main menu is displayed in the header at the top of the page.
 # Acceptable parameters are name, pageRef, page, url, title, weight.
-# 
+#
 # The simplest menu configuration is to provide:
 #   name = The name to be displayed for this menu link
 #   pageRef = The identifier of the page or section to link to
@@ -127,18 +127,23 @@
   pageRef = "pages/about"
   weight = 90
 
- [[footer]]
-   name = "Tags"
-   pageRef = "tags"
-   weight = 10
+[[footer]]
+  name = "Tags"
+  pageRef = "tags"
+  weight = 10
 
- [[footer]]
-   name = "Authors"
-   pageRef = "authors"
-   weight = 20
+[[footer]]
+  name = "Authors"
+  pageRef = "authors"
+  weight = 20
+
+[[footer]]
+  name = "Contribute"
+  pageRef = "pages/contribution_guide"
+  weight = 100
 
 [[footer]]
   identifier = "github"
   pre = "github"
   url = "https://github.com/espressif"
-  weight = 400
+  weight = 400

content/pages/contribution_guide/_index.md

@@ -0,0 +1,14 @@
+---
+title: "Contribution guide"
+date: 2024-04-29T19:22:05+08:00
+draft: false
+description: "Aspects of contributing to the Espressif Developer Portal"
+tags: ["Contribute"]
+---
+
+This post covers all the aspects of contributing to the Espressif Developer Portal.
+
+The major parts are:
+
+- [Content contribution workflow](content-contrib-workflow "Content contribution workflow")
+- [Content writing workflow](content-writing-workflow "Content writing workflow")

content/blog/asciinema_test_post/index.md → content/pages/contribution_guide/asciinema_casts/index.md

@@ -2,11 +2,12 @@
 title: "asciinema casts"
 date: 2024-03-18T10:55:37+01:00
 draft: false
+tags: ["Contribute"]
 ---
 
-## asciinema casts
+## Overview
 
-Now you can easily embed asciinema casts on the Developer Portal. asciinema allows you to record terminal sessions using a lightweight text-based format.
+You can easily embed asciinema casts on the Developer Portal. asciinema allows you to record terminal sessions using a lightweight text-based format.
 
 ### Notable features
 

content/pages/contribution_guide/content-contrib-workflow/index.md

@@ -0,0 +1,107 @@
+---
+title: "Content contribution workflow"
+date: 2024-04-30T14:25:09+08:00
+draft: false
+tags: ["Contribute"]
+---
+
+## Overview
+
+The content contribution diagram below shows how contributions can be done to [espressif / developer-portal][], marked as **Public Upstream**. It is Developer Portal's public GitHub repo.
+
+[espressif / developer-portal]: https://github.com/espressif/developer-portal "Espressif Developer Portal"
+
+```mermaid
+flowchart RL
+    id1[Public \nUpstream]
+    id2[Private \nmirror]
+    id3[Public \nFork]
+    id4[Private \nmirror]
+    id5[Public \nFork]
+    subgraph sg1 [GitHub]
+        id1
+        id3
+        id5
+    end
+    subgraph sg2 [Espressif GitLab]
+        id2
+    end
+    subgraph sg3 [Anywhere]
+        id4
+    end
+    id2 -- Internal \ncontributions \n(private) ---> id1
+    id3 -. External \ncontributions \n(public) .-> id1
+    id4 -. External \ncontributions \n(private) .-> id5
+    id5 -.-> id1
+    style id1 fill:#99f
+    classDef dashedStyle stroke-width:1px,stroke-dasharray: 5 5;
+    class id3,id4,id5 dashedStyle;
+```
+
+The **internal contributions** from Espressif will be prepared in the private mirror on Espressif's GitLab, because during writing and editing, some sensitive information might be mentioned, such as the details of the upcoming products, speculations about future plans, etc.
+
+The **external contributions** can be done in the following ways:
+
+- **Public**: External contributors create a fork of `espressif / developer-portal` and offer a PR.
+- **Private**: External contributors create a private mirror anywhere they want, prepare the material to contribute, and either invite Espressif's reviewers to their private mirror or offer a PR via a fork and have the review done publicly.
+
+## Usage
+
+The workflows for contributions are as follows:
+
+- For public contributions from a forked repo to `espressif / developer-portal`, follow the standard GitHub procedures.
+- For private contributions, see
+  - [How to contribute from Espressif GitLab](#how-to-contribute-from-espressif-gitlab)
+  - [How to contribute from Anywhere](#how-to-contribute-from-anywhere)
+  - [How to set up a private mirror](#how-to-set-up-a-private-mirror)
+
+### How to contribute from Espressif GitLab
+
+To contribute from the private mirror on Espressif GitLab to `espressif / developer-portal`, do the following:
+
+- In GitLab mirror, create a new branch and make the desired updates
+- Invite Espressif's reviewers to do the review
+- Once the private work on the new branch is done, do the following in the GitLab mirror:
+  ```sh
+  # Pull latest updates from upstream main if any
+  git fetch upstream main && git pull upstream main
+  # ! Replace <new-branch> with your branch name
+  git rebase upstream/main <new-branch>
+  # Push the branch with contributions to the public repo
+  git push upstream <new-branch>
+  ```
+- In `espressif / developer-portal`, create a PR from your `<new-branch>` to `main`
+- Remove the merged branch in GitLab mirror
+
+
+### How to contribute from Anywhere
+
+For private contributions from anywhere, do the following:
+
+- Create a private mirror as described in [How to create a private mirror](#how-to-create-a-private-mirror)
+- In your private mirror, create a new branch and make the desired updates
+- Invite Espressif's reviewers to your private mirror to do the review
+- Once the private work on the new branch is finished, do the following in the private mirror:
+  ```sh
+  # Pull latest updates from upstream main if any
+  git fetch upstream main && git pull upstream main
+  # ! Replace <new-branch> with your branch name
+  git rebase upstream/main <new-branch>
+  # Push the branch with contributions to the public repo
+  git push upstream <new-branch>
+  ```
+- After that, fork `espressif / developer-portal` and create a PR from your `<new-branch>` to `main` of `espressif / developer-portal` (public review will be done at this stage)
+
+
+### How to set up a private mirror
+
+To set up a private mirror of `espressif / developer-portal`, do the following:
+
+- Create a private [mirror][create a mirror] of [espressif / developer-portal][]
+- (GitHub only) In the private mirror, consider [disabling][disable a workflow] the existing GitHub workflows as no developer portal deployment can be done from a mirror anyway
+- On GitHub, create a fork of `espressif / developer-portal`
+- In the private mirror, [add][configure a fork] your fork from the previous step as the upstream remote; you will want to push your contributions upstream to create a PR to `espressif / developer-portal`
+
+[create a mirror]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository#mirroring-a-repository
+[disable a workflow]: https://docs.github.com/en/actions/using-workflows/disabling-and-enabling-a-workflow#disabling-a-workflow
+[configure a fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork

content/pages/contribution_guide/content-writing-workflow/index.md

@@ -0,0 +1,57 @@
+---
+title: "Content writing workflow"
+date: 2024-04-29T14:25:01+08:00
+draft: false
+tags: ["Contribute"]
+---
+
+## Before you start writing
+
+There are the following prerequisites before you start writing content:
+
+- Decide how you want to contribute by choosing the [content contribution workflow](../content-contrib-workflow "Content contribution workflow") and get a copy of the [espressif / developer-portal][] repo
+- To view the built version of the website, [install](https://gohugo.io/installation/) Hugo in your environment and go through [Getting started](https://gohugo.io/getting-started/) if required
+
+[espressif / developer-portal]: https://github.com/espressif/developer-portal "Espressif Developer Portal"
+
+
+### Create and view an article
+
+See also the official [docs](https://gohugo.io/getting-started/quick-start/#add-content).
+
+- To create a new article, determine the path and run
+  ```sh
+  hugo new content <path/index.md>
+  # Example
+  hugo new content blog/contribution_guide/index.md
+  ```
+  This assumes that you want to organize the content as a leaf bundle (the usual way). You can also use the [branch bundle](https://gohugo.io/content-management/page-bundles/#comparison).
+- In the created file, change `draft: true` to `draft: false` to make the article visible in the build.
+- To view the changes, in your project folder run
+  ```sh
+  hugo server
+  ```
+
+## Write the content
+
+This is totally up to you how you write the content as long as it is valuable for the community.
+
+For writing and formatting conventions, the contributors at Espressif usually follow the [Espressif Manual of Style](https://mos.espressif.com/) and the *Chicago Manual of Style*. You might find these guidelines useful, but you are not required to follow them.
+
+### Use additional content types
+
+Apart from the usual content types supported by markdown, such as visuals or code snippets, you can also include:
+
+- [Diagrams as code](https://gohugo.io/content-management/diagrams/)
+  - Mermaid diagrams are supported, for an example see the raw version of [this page](../content-contrib-workflow "Content contribution workflow")
+- Youtube videos using [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/#youtube)
+- [asciinema casts](../asciinema_casts "asciinema casts")
+
+If you need other types of content, either create a discussion on GitHub or offer a PR with the required functionality. It will be very much appreciated!
+
+
+## Ask for review
+
+To publish your content on the Espressif Developer Portal, please create a discussion in [espressif / developer-portal][] invite reviewers from Espressif so that they can make sure your content is in-line with Espressif's writing conventions.
+
+After the review is done, create a PR following the [content contribution workflow](../content-contrib-workflow "Content contribution workflow").

layouts/_default/_markup/render-codeblock-mermaid.html

@@ -0,0 +1,4 @@
+<pre class="mermaid">
+  {{- .Inner | safeHTML }}
+</pre>
+{{ .Page.Store.Set "hasMermaid" true }}

layouts/_default/single.html

@@ -56,9 +56,9 @@ <h1 class="mt-0 text-4xl font-extrabold text-neutral-900 dark:text-neutral">
     {{ if or $taxonomyLink $showAuthor }}
     <div class="mb-5"></div>
     {{ end }}
-  
+
   </header>
-  
+
   <section class="flex flex-col max-w-full mt-0 prose dark:prose-invert lg:flex-row">
     {{ if or (and (.Params.showTableOfContents | default (.Site.Params.article.showTableOfContents | default false)) (in
     .TableOfContents "<ul")) (.Site.Params.article.showRelatedPosts | default false) }} <div
@@ -67,13 +67,13 @@ <h1 class="mt-0 text-4xl font-extrabold text-neutral-900 dark:text-neutral">
         lg:top-[140px]{{ else }}lg:top-10{{ end }}">
 
         {{ if and (.Params.showTableOfContents | default (.Site.Params.article.showTableOfContents | default false)) (in
-        .TableOfContents "<ul") }} {{ partial "toc.html" . }} {{ end }} {{ if .Site.Params.article.showRelatedPosts |
+        .TableOfContents "<ul") }} {{ partial "back-to-parent.html" . }} {{ partial "toc.html" . }} {{ end }} {{ if .Site.Params.article.showRelatedPosts |
           default false }} sd {{ end }} </div>
       </div>
       {{ end }}
 
       <div class="min-w-0 min-h-0 max-w-fit">
-        
+
         {{ partial "series.html" . }}
 
         <div class="article-content max-w-prose mb-20">
@@ -88,9 +88,9 @@ <h1 class="mt-0 text-4xl font-extrabold text-neutral-900 dark:text-neutral">
           {{ partial "giscus_dark" . }}
         {{ end }}
 
-        {{ partial "related.html" . }}  
+        {{ partial "related.html" . }}
       </div>
-     
+
     {{ with .File }}
      <script>
         var oid = "views_{{ .Path }}"
@@ -100,7 +100,7 @@ <h1 class="mt-0 text-4xl font-extrabold text-neutral-900 dark:text-neutral">
       {{ $jsPage := resources.Get "js/page.js" }}
       {{ $jsPage = $jsPage | resources.Minify | resources.Fingerprint "sha512" }}
       <script type="text/javascript" src="{{ $jsPage.RelPermalink }}" integrity="{{ $jsPage.Data.Integrity }}"></script>
-  
+
     </section>
   <footer class="pt-8 max-w-prose print:hidden">
 
@@ -119,6 +119,13 @@ <h1 class="mt-0 text-4xl font-extrabold text-neutral-900 dark:text-neutral">
     {{ end }}
     {{ end }}
 
+    {{ if .Store.Get "hasMermaid" }}
+    <script type="module">
+      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
+      mermaid.initialize({ startOnLoad: true });
+    </script>
+    {{ end }}
+
   </footer>
 </article>
-{{ end }}
+{{ end }}

layouts/partials/back-to-parent.html

@@ -0,0 +1,6 @@
+<div
+class="min-w-[220px] py-2 border-dotted border-neutral-300 ltr:-ml-5 ltr:border-l ltr:pl-5 rtl:-mr-5 rtl:border-r rtl:pr-5 dark:border-neutral-600">
+{{ with .Parent }}
+  <a href="{{ .RelPermalink }}">Back to {{ .Title }}</a>
+{{ end }}
+</div>