Product and terminology overview


What is floro & what is a repository?

Floro is a version control system that has similar application and purpose as a headless CMSFloro centers around something called a repository. You can think of a repository as a central location for collaborating on a project or a part of a project. Repositories can belong to an individual or an organization. They can also be public or private. The owner of a repository can control who can view and contribute to their repository. You can make as many repositories as you like in floro.

Repositories can be home to various types of content. You may use a repository to centralize strings for a coding project. You might also use a repository to edit icons, or manage color themes. You might also use a repository to host a content type that doesn't even exist yet. Maybe someone on your team will develop a special spreadsheet application just for you. The possibilities probably aren't endless but there's a lot of them. The key point is that repositories can host various content-types.

As you can see in the image above, repositories are composed of something called plugins.

What do plugins do?

Plugins are the constituents of repositories. They're small applications used for editing a certain content type. Plugins can do nearly anything a website can do. The big difference between a plugin and a traditional web application, is plugins do not control your data, you do!

This is a screenshot of a plugin being used to create the text on this page.

Plugins do not require an internet connection for you to make edits to your content. They may have certain features that require you to be online though. For example, in the above screenshot you may notice there is a GPT feature that allows me to request edit suggestions from ChatGPT. If I lose internet connection, this feature will not be available to me. However, a loss of internet connection does not prevent me from editing this document. This is because plugins do not save your content to a remote database. In fact, they don't have databases, they use the local repository on your computer to save your content. Furthermore, the data saved by a plugin won't ever be sent to a remote server, unless you explicitly tell floro to do so.

Presumably, you eventually want some of your edits to sync with someone else's changes. The really cool thing about plugins is that multiple authors, can work on the same content of a plugin, for the same repository, at the same time and eventually end up with a controlled, and precise amalgam of their edits. For this to work out we need version control.

What is version control?

Have you ever saved a Google Doc or Microsoft Word file to something like "My Document.docx" only to realize two seconds later that you needed to make a change and then renamed your document to "My Document Final.docx"? ... Then to "My Document Actual Final.docx" then "My Document (I'm serious this time) Final.docx", then "My Document (Last time I was joking but this time I really mean it) Final.docx"?

If you can relate, then you know the initial problem version control set out to solve over 50 years ago. On a fundamental level, all version control systems work something like video game checkpoints. If you mess something up, or need to revisit an earlier point of edits, you can always hop back in time to that checkpoint. You've likely experienced versioning features in applications like Google Docs, Microsoft Word, Notion, or even Figma.

While many applications have a sense of versioning, to get precise synchronization results we have to have a slightly different mental model of what a document really is. When we edited "My Document.docxand saved "My Document Final.docx", what did we really do?

What are diffs, commits, SHAs, and work in progress (WIP)?

Prior to committing your changes, your edits still get saved to your computer. Before these changes end up in your version tree, we say the changes are a work in progresswhich we acronymize to WIP. If you've ever worked on a document where you constantly had to save the file in order to not lose progress, you're familiar with what a WIP is. To be clear, even if you shut down floro without committing your work, your WIP will still be there (don't worry). WIP states are just impermanent until they are committed.

Going back to our checkpoint analogy, diffs are the differences between two versions of a document. While commits are the explicit checkpoints you create. A commit stores the differences between the prior version of a document and the version at the time of committing. Commits also store the author of the commit, the time the commit was created, as well as a short message summarizing the changes.

After we commit our changes, we will see that the commit we created has a unique identifier associated with it called a SHA. A SHA is an identifier that is the product (hash) of the diff, the prior commit's SHA, the commit message, the author's username, and the time at which the commit occurred. Sometimes in version control systems, we use the terms commit and SHA interchangeably. While a SHA is a 64 character string that describes a commit, you may sometimes see that SHA is used to describe an entire commit. In floro we usually display only the first 4 to 8 characters of a SHA. This makes reading SHAs far easier to remember and keep track of.

In the image above you may notice that there are two labels stemming from the same initial commit. These are what we call branches.

What are branches?

The easiest way for me to conceptualize branches it to think of them as subway lines. They may start off at the same initial station but ultimately they go off in different directions. Branches provide a way for you to experiment without fear of accidentally ruining your document. They also are a convenient way of allowing multiple members of the same team to work from the same starting point without stepping on each other's toes.

In floro branches can have parent branches. The goal of a branch is to be eventually merged back into its parent and then deleted.

As you can see in the above image. I'm currently working on a branch called "added product docs", the parent branch (also called the base branch) of my branch is called "main."

My goal is to eventually merge my branch (added product docs) back into mainTo do this I need to push my branch to a remote server.

What is a branch's head?

A branch's head is the commit a branch currently points to. When you commit a change on a branch, the branch head is updated to the new commit. When you pull changes from a remote repository, or merge a branch, the branch head is updated. A branch can always be reset to a previous (or future) point by changing the branch's head.

What is pushing?

You can think of pushing as being nearly synonymous with uploading. Remember, all the changes I make reside on my computer alone. They won't automatically sync to a cloud or anything like that. When I'm ready for the changes in my branch to be reviewed by someone else, I can push my branch to the remote repository.

If you look in the lower right corner of the image above, you will see there are two buttons pull remote and push local. When you click push local  you will upload your changes to the remote repository. Up until this point, everything we have done has been offline. When we switch the tab in the upper right corner, from Local to Remote, we now should see a prompt to create a merge request for our branch.

What is a merge request?

A merge request is a remote representation of your branch. The reason they are called merge requests is because they are a way for your peers to review your changes and grant you permission to merge your changes into the main branch. 

As you can see. In the merge request above, you can view the changes or the commits of the branch. You and your peers can also comment on the changes made.

Normally, you wouldn't be able to merge a merge request without peer approval. There's usually some back and forth, where revisions are requested. Once you make your revisions locally, you must push any new commits you make locally for them to appear in your merge request.

In the repository in this example, I have administrative access that allows me to merge my branch without requiring peer approval. When I press the button that says "merge branch and close," I will not be merging the changes on my local repository. The merged changes will be made in the remote repository. If I switch to the main branch in my local repository, I will not see the updated changes. Why is that?

Just as floro requires you to explicitly push changes to a branch, floro also requires you to explicitly pull changes as well.

What is pulling?

You can think of pulling as being nearly synonymous with downloading. When a remote branch has changes that you do not have on your local version of the branch, you will see an option to pull down the changes for the branch. If you have any local changes that have not been pushed to the remote branch, pulling will merge your local changes with the remote changes for the branch. 

In the image above, you can see the pull remote option is available to us now. We should highlight we switched our local branch from "added product docs" to "main." 

After we pull, our local repository and our remote repository should be in sync. This is how version control allows us to collaborate with others, while being able to work independently and concurrently. If we want to, we can now delete the  "added product docsbranch locally. Our commits will still always be there but we no longer need the branch.

What is a default branch and what are feature branches?

In the workflow we just described, we threw around the word branch kind of liberally. Technically we could say all branches are created equal. In practice, there's a big distinction between two classes of branches.

The branch we created before, "added product docs,"  is what we would call a feature branch. Every floro repository automatically has a branch called "main," this branch is the default branch

Generally speaking, you should only make changes to feature branches. Furthermore, the parent branch of your feature branches should almost always be main or whatever is the default branch of your repository.

The only interaction you should have with the main branch locally is that you should pull it to sync remote updates to your local repository. The way main gets modified is through merging merge requests.

As rule of thumb, you pull the main (default) branch and push your feature branches. There are some exceptions and a few other common interactions we will discuss later in the documentation.

What is merging?

Merging is a term we threw around a bunch without really explaining what it is. We will cover merging in much greater depth in later parts of the documentation.

Merging is the process of taking the changes we made in our feature branch added product docs and combining them with the changes made in the main branch by others. You don't have to do anything special but press the "merge button" to merge locally or in the case of a merge request, press "merge branch and close" (as we showed in the example above).

Merging can occur both locally and remotely. Usually, when we merge locally, we are merging the main branch (or the base branch) into our feature-branch.

What are merge conflicts?

Sometimes we won't be able to merge our changes without resolving a conflict. Floro will warn us when there is a conflict. A conflict occurs when two branches have incompatible changes. For example, if someone else were editing this paragraph simultaneously, whomever, merged their branch into the main  branch second, would have to reconcile the conflict between the two paragraphs. We wouldn't be able to merge a merge request without addressing the merge conflicts locally first. Remote branches must be conflict-free in order to be merged.

When we need to address a merge conflict we have to pull down the main branch. We do this by first switching from our feature branch to the main branch and clicking pull remote. Next, we switch back to our feature-branch. Finally, we press compare, and select the main branch to compare our changes against. We should then see the option to merge the changes from main into our feature branch. From there we will be able to resolve the conflict and push up our resolved changes.

We will cover this entire process in much greater detail later. Hopefully, this is enough context to make sense of the process we went through above.

Next Section

That was a lot. If you're ready, we're ready to start diving into each section of the product. 

We'll first be covering navigating the user portal.