Skip to content

Upgrade workflow

Jump to bottom
Martin Minkov edited this page Oct 31, 2023 · 10 revisions

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.

O(1) Labs looking into possible upstream automation to 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 will create 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. 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 can check out the major-upgrade branch, you need to fetch all branches from the upstream repository to ensure that your local clone is aware of it. Run:
git fetch upstream
  1. Check if 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, contributors should pull the latest changes from the major-upgrade branch on the upstream repository. This ensures that they are not missing any updates that have been made since they last pulled or cloned the repository.

git pull upstream major-upgrade

Making Changes and Pushing to the major-upgrade Branch

Once 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: Once you’re satisfied with your changes, you need to stage them, 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 the contributor last pulled, they may need to resolve merge conflicts. Git will provide information on which files have conflicts, and the contributor will 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). Below is a step-by-step guide on how to do this:

  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 & Pull Request:
  • Once you are in your forked repository, navigate to the major-upgrade/feature-branch (replace feature-branch with your actual branch name).
  • You should see a “Compare & pull request” button. Click on it.
  • If you don't see the button, switch to the major-upgrade branch, click on "New pull request", and manually select your feature branch.
  1. Create Pull Request to Upstream:
  • On the next screen, you should see the base repository and base branch at the top. The base repository should be your forked repository. You need to change it to the upstream repository (o1-labs/docs2).
  • Click on 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 & 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, or screenshots.
  1. Merging into major-upgrade:
  • Once 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 sections of the guide to do this.

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 should list 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: Once 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 will merge featureBranchB from contribB’s fork into your myFeatureBranch.

  1. Resolve Any Merge Conflicts: If there are merge conflicts, Git will notify you, and 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