Repo Basics

Where is the Repo?

The official Fluid Framework code repository resides on GitHub. In the next few steps, we will look at how to create our own fork of the official repository and set up a local git clone.

If you are not familiar with git or GitHub, please take a look at this introduction to familiarize yourself with fundamental git concepts such as cloning, branching, forking etc.

Forking the Repo

We are now going to create your own personal fork of the entire repo. This will give you a sandbox environment to add and remove any changes as you wish. You will have full freedom to do whatever you want on this fork.

We will establish upstream hooks later on to allow you to pull updates from the official repo, and submit pull requests to add changes to the official repo.

Please go to the repo and click "Fork". Then choose your personal account.

Awesome! Now you should be on a page with a URL that looks like "https://github.com/{YOUR-USER-NAME}/FluidFramework". This is your own fork of the most current version of the repo, hot off the presses!

Let's get it onto your local machine now!

Cloning the Repo

Over the following steps, we will clone the repo and add upstream remote connections to the official repo so that you can fetch updates from it in your own master branch.

The remote you fork from is most often referred to as upstream, and we will use that name in this example. But you can name it microsoft, ms, etc. as you wish.

1. With our own fork available now, we can clone it using the command line tool of your choice

git clone https://github.com/{YOUR-USER-NAME}/FluidFramework.git

2. Now, we will add the upstream remote to the official version of the repo.

git remote add upstream https://github.com/microsoft/FluidFramework

3. With that added, we will fetch any new updates from the official repo.

git fetch upstream

4. Now, we want our fork's master branch to track the official repo's master so that we always get the latest code there when we pull

git branch master --set-upstream-to upstream/master

You can also optionally set a different branch to track the official repo, if you'd like to keep your personal master separate. But you will need to remember to merge with that branch prior to submitting any changes to the official repo.

5. Pull the contents of upstream/master to your local master, since it was previously tracking your forked copy of the repo

git pull

6. Optional - Prevent yourself from ever pushing a branch to upstream by setting the upstream remote to an invalid URL. All developer branches should instead be merged into the official repo using the Pull Request process.

git remote set-url --push upstream no_push

And now, we should have our personal repo all set up! We can quickly run

git remote -v

to verify that everything is setup correctly. It should look something like this.

upstream       https://github.com/microsoft/FluidFramework (fetch)
upstream       no_push (push)
origin  https://github.com/{YOUR-USER-NAME}/FluidFramework.git (fetch)
origin  https://github.com/{YOUR-USER-NAME}/FluidFramework.git (push)

Editing the Repo

With your local version of the code now setup, let's walk through how to start making changes.

1. Get the latest changes from the official repo using our upstream remote

git checkout master
git pull

2. Create and checkout a new local branch to start making changes on

git checkout -b {YOUR-LOCAL-BRANCH}

3. At this point, you can add any changes using the normal git add and git commit commands.

When you are ready to push to your fork, use the following

git push --set-upstream origin {YOUR-LOCAL-BRANCH}

This is only needed the first time you push your branch. Any subsequent pushes only need a git push

4. With the branch now available on your remote fork, we can go to the official repo website and you should see a prompt requesting you to make a Pull Request

Go ahead and click "Compare and Pull Request".

This will automatically select the official repository's master branch as the target for the merge and display your changes.

Alternatively, you can also navigate to Pull Requests. Here, click "New Pull Request" and you will see this.

Here, you will need to click on "compare across forks" to start seeing the branches on your fork. Select your fork in "Head repository" and your branch in "compare" for the source:

5. Now you can simply click "Create Pull Request" to start the review process. Alternatively, you can also create a "Draft Pull Request" if the branch is still a work-in-progress.

Legal

You will need to complete a Contributor License Agreement (CLA) to submit changes. This agreement testifies that you are granting us permission to use the submitted change according to the terms of the project's license, and that the work being submitted is under appropriate copyright. Upon submitting a pull request, you will automatically be given instructions on how to sign the CLA.