Skip to main content

Contribution workflow

·3 mins·
Contribute
Author
Kirill Chalov
Senior technical writer at Espressif

Overview
#

The 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.

flowchart RL
    id1[Public
Upstream] id2[Private
mirror] id3[Public
Fork] id4[Private
mirror] id5[Public
Fork] subgraph sg1 [GitHub] id1 id3 id5 end subgraph sg2 [Espressif GitLab] id2 end subgraph sg3 [Anywhere] id4 end id2 -- Internal
contributions
(private) ---> id1 id3 -. External
contributions
(public) .-> id1 id4 -. External
contributions
(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:

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:
    # 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:

  • Set up a private mirror as described in How to set up 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:
    # 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 of espressif / developer-portal
  • (GitHub only) In the private mirror, consider disabling 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 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

Related

asciinema casts
2 mins
Contribute
Overview # asciinema allows you to record terminal sessions using a lightweight text-based format. You can easily embed asciinema casts on the Developer Portal.
Writing content
6 mins
Contribute
Before you start writing # There are the following prerequisites before you start writing content: