Contribution workflow

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 [Third-party server]
        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;

Pick the workflow that matches your situation:

1. Public fork on GitHub — external contributors (usual path)
2. Private mirror on Espressif GitLab — Espressif staff
3. Private mirror on a third-party server — advanced / rare

Public fork on GitHub

#

This is the default way to contribute to espressif / developer-portal.

1. Fork espressif / developer-portal. On how to do it, follow the GitHub’s fork a repository guide.
2. Clone your fork (replace <your-username> with your GitHub username). Submodules are required; use a shallow fetch to keep the clone smaller:

   git clone --recursive --shallow-submodules https://github.com/<your-username>/developer-portal.git
   cd developer-portal
   

3. Create a feature branch for your work:

   git switch -c my-feature-branch
   

4. Make your changes, commit, and push the branch to your fork.
5. Open a pull request against main on espressif / developer-portal. See GitHub’s creating a pull request guide for the UI steps and branch comparison.

Private mirror on Espressif GitLab

#

Espressif contributors prepare changes in the private GitLab mirror, then they are sync-merged to the public upstream after review.

1. In the GitLab mirror, create a feature branch and add your changes.
2. Open a merge request and invite Espressif reviewers.
3. After review and approval, the branch is sync-merged to espressif / developer-portal on GitHub.

Private mirror on a third-party server

#

Use this only when you need a private workspace (for example, a private GitHub mirror).

1. Create a private mirror of espressif / developer-portal.
2. (GitHub only) In the private mirror, consider disabling existing GitHub workflows as deployment cannot run from a mirror anyway.
3. On GitHub, fork espressif / developer-portal.
4. In the private mirror, add your fork as upstream so you can push reviewed branches there before opening a public PR to espressif / developer-portal.
5. In the private mirror, create a branch, make your changes, and invite Espressif reviewers.
6. When the private review is done, push the branch to your fork.
7. Create a pull request from your fork’s <new-branch> to espressif / developer-portal’s main for the final public review.