04 — Repo, Git, and GitHub Orientation

A new team member encountering a serious software repository for the first time often has the same reaction: it looks larger, stranger, and more coded with hidden meaning than it really is. Folder names seem loaded. Commands seem magical. Git history looks like a second language. GitHub appears to be a public control room where everyone already knows what they are doing. That feeling is normal. It is also misleading.

The repo is not magic. It is a structured working environment.

To understand it properly, the reader has to begin with the simplest point. A repository is the tracked body of the project. It is where the code lives, where the documentation lives, where training materials live, where configuration files live, where scripts live, and where the history of all meaningful tracked changes is preserved. In a serious company, the repo is not just a storage folder. It is the working memory of the project.

That last phrase matters. The repo is not only where files sit. It is where the project remembers what it is.

Without that memory, the system would quickly become fragile. Files would be edited in place with no disciplined history. Documentation would drift. Training material would fork into conflicting versions. Good ideas would disappear into local machines. Bad changes would be hard to reverse. Nobody would be quite sure which version of the project counted as real. That is exactly the kind of chaos Git and GitHub are meant to prevent.

Git is the version-control system that makes the repo behave like a tracked history rather than a pile of overwritten files. In plain language, Git keeps a record of change. It allows the project to move forward while preserving what existed before. It makes it possible to compare one state of the project against another, to recover older states, to branch work safely, and to understand how the system evolved over time. A person who understands Git begins to understand that the repo is not static. It is a living structure of remembered change.

GitHub sits on top of that as the hosted collaboration environment. If Git is the history engine, GitHub is the public workshop built around that engine. It is where branches are shared, where pull requests are reviewed, where project history becomes visible, where releases can be tagged, and where collaboration stops being trapped on one local machine. GitHub is not the project itself; it is the main remote collaboration surface for the project.

That distinction is worth keeping clear. Git is the underlying version-control system. GitHub is the hosted platform used to store and collaborate around Git repositories. The two are related, but they are not the same thing.

Once that is clear, the next important concept is the branch.

A branch is a separate line of work inside the same project history. The reason branches exist is simple: serious projects cannot safely evolve if every idea, every experiment, every documentation revision, and every fix is made directly on the same central line all the time. Branches create protected lanes. One branch can be used for a feature. Another for a hotfix. Another for a documentation overhaul. That does not mean the work is disconnected from the project. It means the work is being developed in a controlled lane until it is ready to be reviewed and merged back.

This matters a great deal in a project like SUMMA because the system is not just code. It is code, documentation, training, exports, product concepts, internal language, and deployment structure all moving at once. Branches allow that movement to happen without turning the repo into an unsafe editing field.

Inside a branch, work accumulates through commits.

A commit is one saved checkpoint in the project’s history. It captures a selected set of changes and gives that checkpoint a message explaining what was done. A new reader should think of a commit as a durable memory point. It says: at this moment, these tracked changes became part of the recorded project history. Good commit discipline matters because project history is only as intelligible as its checkpoints. A vague commit message weakens the history. A clear one strengthens it.

If branches are work lanes and commits are history checkpoints, then a pull request is the formal gate where one lane asks to join another.

A pull request, usually shortened to PR, is not merely a technical formality. It is one of the main quality-control mechanisms in a serious repository. A PR says: here is the work done on this branch; here is the difference from the target branch; now inspect it, discuss it, review it, and decide whether it should become part of the main project line. This matters because projects degrade quickly when unreviewed work flows directly into the central branch without discipline. Review is not bureaucracy for its own sake. It is how the repo protects itself from sloppiness, confusion, and accidental damage.

Merging is what happens when a reviewed branch is accepted into the target branch. In simple terms, merge means the line of work rejoins the main line of the project. Sometimes that is smooth. Sometimes there are merge conflicts, which simply means Git found competing edits that it could not reconcile automatically. A merge conflict is not a sign that something is broken. It is a sign that two lines of history touched the same area and now need a human decision.

For a new team member, this is the right mental model: the repo is a working structure; Git remembers its history; branches create safe work lanes; commits create saved checkpoints; pull requests create review gates; merges bring approved work back into the main project line.

Once that structure is understood, the rest of the technical environment begins to make more sense.

The repo does not only contain code. In SUMMA, it also contains Markdown manuals, training chapters, README anchor files, docs-site configuration, export helpers, scripts, and architecture lanes. This matters because a modern legal-tech company is not only built out of executable code. It is also built out of disciplined explanation. Documentation is not a side effect. It is part of the product environment itself. A weak documentation culture produces weak onboarding, weak continuity, and weak understanding of the machine.

That is why Markdown matters in this project. Markdown is simply the text format used to write structured docs in a clean, durable way. It is intentionally lighter than a word processor and easier to track inside the repo. The internal manual, the docs portal, and much of the training environment are written in Markdown because Markdown works well with version control, review, and publication.

That publication layer is where MkDocs and Netlify enter.

MkDocs is the static-site generator used to turn the project’s Markdown documentation into a readable docs website. In plain language, it takes source writing and turns it into a navigable manual site. Material for MkDocs is the visual layer on top of that system. It controls how the documentation looks and behaves for the reader. Netlify is the hosting platform used to publish that built site so it can be viewed through a browser outside the local machine.

This introduces an important technical distinction: source, build, and deploy.

The source is the original Markdown and config material written by the team. The build is the process that converts that source into a usable static website output. The deploy is the act of publishing that built output to a hosting environment such as Netlify. These three things are related, but they are not identical. A new reader should learn to separate them mentally. Writing the source is not the same as building the site. Building the site is not the same as deploying it. A great deal of beginner confusion comes from blurring those stages together.

The same kind of clarity matters in the local environment.

When a team member uses Terminal, works in a Python virtual environment, runs mkdocs serve, runs mkdocs build, or checks git status, they are not performing exotic wizardry. They are interacting with the repo through its technical control surfaces. Terminal is simply the command-line environment. The shell is the command interpreter. The virtual environment isolates project dependencies. serve creates a local preview server. build generates output. deploy publishes that output. All of this becomes much less intimidating once the reader understands that each command is just one operation in a structured workflow.

A serious technical culture depends on that demystification. People do not need to be fearless to work well, but they do need to stop mythologizing the repo. The repository is not a monster. It is a machine with names, parts, stages, and discipline. Once those are understood, the reader can move through it with increasing confidence.

The reader should leave this chapter with one central idea: the technical side of SUMMA is not random and it is not mystical. It is a tracked, structured, reviewable working environment designed to let serious code, serious documentation, and serious product thinking evolve safely over time. Git and GitHub are not distractions from the product. They are part of the machinery that makes the product trustworthy.