Contributing

Contributing to the Fluid Framework

If you'd like to contribute to the Fluid Framework open source codebase, first of all, thank you! We'd love to see your ideas and appreciate your contributions, whether they be in the form of bug reports, idea suggestions, code submissions, or just trying out our platform.

We have tried to make it as easy as possible to set up your local clone of the Fluid Framework so that you can hit the ground running. Let's get started!

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.

Building and Running the Repo

The only pre-requisites for running the Fluid Framework code are:

• Git LFS (included by default with most Git installations)
• Node v12.x
• Docker (only required for running the routerlicious server docker image locally, not needed for just running client component packages)

With these dependencies installed, simply navigate to the FluidFramework directory and run the following two commands:

npm install
npm run build:fast

This will automatically install all dependency packages, and then build & compile the entire FluidFramework codebase.

When it has successfully finished, your output will look similar to this

The first time you run these commands, they will take some time as it is downloading all of the dependencies and setting up symlinks for the local packages to be able to use them. Any subsequent runs should be much faster.

npm install will only re-download packages that were not present locally or ones that were updated

npm run build:fast will only re-compile code that has been edited, and any code that is dependent on the edited code. It will skip the tasks for any unedited code.

Running Client Code

Running a Specific Component

1. Navigate to the specific component directory from the repo root, i.e. for Clicker this is

cd ./components/examples/clicker

2. Start the component

npm run start

3. Open you browser and navigate to the http://localhost:8080 to see two renders of Clicker side-by-side. The two represent two different clients rendering Clicker using a local in-memory server.

You can think of the user on the left as User A and the right as User B. When one user clicks, the clicker increments for both users since it is a synced Fluid component. This allows you to quickly test cross-client behavior locally without needing a second device.

You will also have noticed that something got added to the URL and it looks similar to "http://localhost:8080/second-hand-shop". The bit after "http://localhost:8080/" is a random string used to represent different sessions.

That's why, if you refresh the page using the same URL, you will see that the Clicker count is persistent since it reloads the same session.

To load a new session, simply change the string or remove it all together. You will see that on the new page, Clicker once again starts from 0.

4. To open another component simultaneously, just navigate to its directory in a separate terminal window and run npm run start again. It will now load the second component in http://localhost:8081 since 8080 is already in use.

Editing Components

You can dynamically edit components while they are running! Simply run the component as described above, using npm run start and edit away!

Single Package Changes

As long as the changes are local to the component package itself, the script running the component will automatically recompile when you save your changes and refresh with your updates.

It's usually a good idea to update the string at the end of your "http://localhost:8080/" URL after this as the older session storage may be corrupted from your older code. Starting a new session by changing the string will give you a clean environment.

Cross-Package Changes

If you are editing code across multiple packages, you will need to run npm run build:fast again to have your component pick these changes up.

Clicker, for example, has dependencies on the @fluidframework/aqueduct package. If we modified code in aqueduct and we needed Clicker to pick these up, simply re-run npm run build:fast from the repo root.

If this is not the first build, it will only re-build @fluidframework/aqueduct and any packages that depend on it (including Clicker). All other packages will be ignored as there is no change there.

Running Server Code

Running a Local Tinylicious Server

1. Navigate to the ./server/tinylicious directory and build it.

npm i
npm run build

NOTE: You will get some errors on install from kafka-node if you don't have Python, Visual Studio, and Desktop Development with C++ Workload installed – these are safe to ignore, since they are from an optional dependency (more info).

2. If the build succeeds, start the tinylicious server

npm start

3. Now, we can run components against this server. We will use Clicker as an example. Navigate to the Clicker directory and start the component using the start:tinylicious command

cd ./components/examples/clicker
npm run start:tinylicious

This command is running the following script for reference

webpack-dev-server --config webpack.config.js --package package.json --env.mode tinylicious

4. Now navigate to http://localhost:8080 to see Clicker running on tinylicious

NOTE: tinylicious stores persisted data on your filesystem at /var/lib/tinylicious. On Windows, this will be C:/var/lib/tinylicious. If you want to clear everything and start fresh, then shut down tinylicious and delete that folder. The next time you start tinylicious everything should be as new.