Skip to content

Upgrade workflow

Jump to bottom
Barrie Byron edited this page Feb 26, 2024 · 10 revisions

Major upgrade workflow

TLDR; The major-upgrade branch always has a deploy URL of the latest merged changes.

To view your progress of all merged PRs into `major-upgrade:

https://docs2-git-major-upgrade-minadocs.vercel.app/

Node operator doc work by Mina Foundation for the major upgrade

TLDR;

  1. Fork the https://github.com/o1-labs/docs2 repository.
  2. Create PRs against the major-upgrade (https://github.com/o1-labs/docs2/tree/major-upgrade) branch, not main.
  3. Be sure to keep the major-upgrade branch current.
  4. All PRs for the major upgrade get merged into the major-upgrade branch.
  5. When it's time, a single PR that includes all of the updates gets merged into main.

To prepare for the major-upgrade to main docs PR merge, periodically merge the main branch into the major-upgrade branch:

git checkout main

git pull

git checkout major-upgrade

git merge main

Goal: Keep the major-upgrade branch current with main.

Forking the Repository

  1. Navigate to the docs2 repo.
  2. Fork the repository: Click the Fork button located at the top-right corner of the repository page. This action creates an independent copy of the repository under your GitHub account.

Cloning the Repository Locally

  1. Open your terminal/command prompt: Launch your terminal or command prompt.
  2. Navigate to your desired directory. Use the cd command to move to the directory where you wish to clone the repository.
  3. Clone the repository: Type git clone https://github.com/your-username/docs2.git, replacing your-username with your GitHub username.

Adding a Remote

  1. To add the original repository as a remote, run:
git remote add upstream https://github.com/o1-labs/docs2.git

This links your local clone to the original docs repo, enabling you to stay in sync with the latest changes.

Switching to major-upgrade branch

  1. Fetch all branches from upstream. Before you check out the major-upgrade branch, you must fetch all branches from the upstream repository to ensure that your local clone is aware of it. Run:
git fetch upstream
  1. Check if the major-upgrade branch exists locally. Run the following command to list all branches, including remote branches:
git branch -a | grep "major-upgrade"

Look for remotes/upstream/major-upgrade. If it’s there, then you can proceed to the next step. If not, make sure you have correctly added the upstream remote and fetched the branches.

  1. Check out the major-upgrade branch. If the branch exists remotely, you can check it out to your local machine using:
git checkout -b major-upgrade upstream/major-upgrade

This command creates a new branch called major-upgrade in your local repository and sets it to track the major-upgrade branch from the upstream repository.

Pull the Latest Changes

Before pushing changes, you must pull the latest changes from the major-upgrade branch on the upstream repository. This ensures that you are not missing any updates that have been made since you last pulled or cloned the repository.

git pull upstream major-upgrade

Making Changes and Pushing to the major-upgrade Branch

After you have checked out the major-upgrade branch locally, you are ready to start making your changes. Make sure you are working off of major-upgrade before doing this step. To check, run:

git branch

It should show major-upgrade. If it doesn't, see the Switching to major-upgrade branch section.

Here’s how you can add your changes and push them to your forked repository:

  1. Create a new branch for your changes:
git checkout -b feature-branch
  1. Make your changes: Edit, add, or delete files as necessary for the documentation update.
  2. Stage your changes: After you’re satisfied with your changes, stage the changes, which means marking them for inclusion in your next commit. Run:
git add .

The . adds all changed files in the current directory and its subdirectories. If you want to add specific files, you can replace . with the file paths. 4. Commit your changes: After staging your changes, you need to commit them, which saves them to your local major-upgrade branch. Run:

git commit -m "A clear and concise commit message"
  1. Push to your Forked repository. Now that your changes are committed locally, you need to push them to your forked repository on GitHub. Run:
git push origin feature-branch

Resolve any Merge Conflicts

If there have been other changes to the major-upgrade branch since you last pulled, you might need to resolve merge conflicts. Git provides information on which files have conflicts, and you need to manually resolve these conflicts.

Creating a Pull Request from Fork to Upstream

After you have pushed your changes to your forked repository, the next step is to open a Pull Request (PR) to merge these changes into the major-upgrade branch of the upstream repository (the original repository from which you forked).

A step-by-step guide:

  1. Navigate to your fork on GitHub:
  • Open your web browser and go to your GitHub profile.
  • Navigate to your fork of the repository.
  1. Compare and Pull Request:
  • After you are in your forked repository, navigate to the major-upgrade/feature-branch (replace feature-branch with your actual branch name).
  • Select the Compare & pull request button.
  • If you don't see the button, switch to the major-upgrade branch, select New pull request, and manually select your feature branch.
  1. Create Pull Request to Upstream:
  • On the next screen, you will see the base repository and base branch at the top. The base repository is your forked repository. You must change the base repository to the upstream repository (o1-labs/docs2).
  • Select the base repository dropdown and select o1-labs/docs2.
  • IMPORTANT: Ensure that the base branch is set to major-upgrade.
  • Your feature branch in your forked repository should already be selected.
  1. Review and Create Pull Request:
  • Add a title to your pull request. Make it clear and concise.
  • Fill out the description with all the details about the changes you are making. Include any relevant information, links to issues and docs, or screenshots.
  1. Merging into major-upgrade:
  • After the maintainers approve your pull request, they can merge it into the major-upgrade branch of the upstream repository.
  • If you have the necessary permissions, you may also be able to merge the pull request yourself after approval.
  1. Sync Your Fork:
  • After your pull request has been merged, make sure to sync your fork and local clone with the upstream repository to ensure you have the latest changes.
  • Follow the steps outlined in the previous Pull the Lastest Changes sections of the guide.

Pulling Specific Branches from a Contributor's Fork

When working on a collaborative project using Git and GitHub, there might be a situation where you need to integrate changes from a specific branch of another contributor's fork into your current branch. This can help ensure compatibility and allow you to work with the most up-to-date version of the project.

Example Scenario:

Your GitHub username: myUsername Other Contributor's GitHub username: contribB Branch you are currently working on: myFeatureBranch Branch from contributorB's fork you want to pull: featureBranchB

Steps to Pull Changes:

  1. Add the other contributor's fork as a remote: First, you need to add a remote that points to the other contributor’s fork of the repository. If you haven’t done this already, you can add it using the git remote add command.
git remote add contribB https://github.com/contribB/docs2.git

Verify that the remote has been added:

git remote -v

This command lists all the remotes for your repository, including contribB.

  1. Fetch the specific branch from the contributor's fork: Next, fetch the specific branch from the contributor's fork that you need.
git fetch contribB featureBranchB

This command fetches featureBranchB from contribB's fork.

  1. Merge the fetched branch into your current branch: After the branch is fetched, you can merge it into your current working branch.

First, make sure you are on your working branch:

git checkout myFeatureBranch

Then, merge the fetched branch:

git merge contribB/featureBranchB

This command merges featureBranchB from contribB’s fork into your myFeatureBranch.

  1. Resolve any merge conflicts: If there are merge conflicts, Git notifies you. You’ll need to resolve these conflicts manually. Open the conflicting files, make the necessary changes, and then add and commit the resolved files.
git add .
git commit -m "Resolved merge conflicts"
  1. Push the changes to your fork: After resolving any conflicts and completing the merge, push the changes to your fork.
git push origin myFeatureBranch

Now, you have successfully pulled changes from a specific branch of another contributor's fork into your current branch, ensuring that you are working with the most up-to-date and compatible version of the project.

Mina Docs

Clone this wiki locally