path: root/book/module2/version_control.tex

\section{Version Control Software}\label{version-control-software}

\subsection{What is Version Control}\label{what-is-version-control}

Version control is a system that tracks changes to files, enabling
developers to collaborate, manage code history, and revert to previous
versions when needed. The most used version control software (VCS) is
git. In this course git is the VCS we will be using.

In the open-source community VCS is the - Tracks changes and history. -
Enables collaboration among developers. - Reduces errors by managing
code versions. - Supports branching and merging for parallel
development.

In this section is divided up into two major sections. The first section
\emph{Git} will cover the basics of how to create backups of your
project. The second section will cover how to use git with GitHub to
\emph{collaborate} on projects.

\subsection{Git}\label{git}

Git is a version control program that tracks changes to files and
directories using snapshots. It is a distributed version control system,
meaning that each developer has a complete copy of the repository on
their local computer. Git is the most widely used version control system
and is popular among developers for its speed, flexibility, and
efficiency.

\subsubsection{The Three States}\label{the-three-states}

Pay attention now --- here is the main thing to remember about Git if
you want the rest of your learning process to go smoothly. Git has three
main states that your files can reside in: modified, staged, and
committed:

\begin{itemize}
\tightlist
\item
  \textbf{Modified} means that you have changed the file but have not
  committed it to your database yet.
\item
  \textbf{Staged} means that you have marked a modified file in its
  current version to go into your next commit snapshot.
\item
  \textbf{Committed} means that the data is safely stored in your local
  database.
\end{itemize}

This leads us to the three main sections of a Git project: the working
tree, the staging area, and the Git directory.

\includegraphics{figures/git_areas.png} \#\#\# Branching In git,
branches allow for parallel workflow on a project. It give contributors
the ability to work different features at the same time. Each branch
represents an independent line of development, and once a feature or fix
is complete, it can be merged back into the main branch. Here is a
common branching structure used in many Git projects: - Main Branch -
The main branch (a.k.a. master branch) is the default branch in a Git
repository and contains the stable version of the code. - Development
Branch - is created to develop a new feature or fix a bug without
affecting the main branch. It isn't necessarily always stable, but
whenever it gets to a stable state, it can be merged into master. -
Topic Branch - A topic branch is a short-lived branch that you create
and use for a single particular feature or related work.
\includegraphics{figures/git_silo_branching.png} \#\#\# Best Practices -
Use descriptive commit messages. - Commit early and often. - Keep
commits focused on a single change. - Use feature branches for new
features or bug fixes. - Review and test changes before merging. -
Resolve conflicts promptly. - Keep the commit history clean and
organized.

\subsubsection{Basic Commands}\label{basic-commands}

Here is a list of some git commands to get you started. \#\#\#\#
Starting your repository - \texttt{git\ init} - Initialize a new Git
repository. - \texttt{git\ clone} - Clone an existing repository.
\#\#\#\# Committing - \texttt{git\ status} - Check the status of the
repository. - \texttt{git\ add} - Add files to the staging area. -
\texttt{git\ commit} - Commit changes to the repository. \#\#\#\#
Branching - \texttt{git\ branch} - List, create, or delete branches. -
\texttt{git\ checkout} - Switch between branches. \#\#\#\#
History/Inspection - \texttt{git\ log} - View the commit history.
\#\#\#\# Collaborative - \texttt{git\ fetch} - Fetches updates from a
remote but does not merge. - \texttt{git\ merge} - Merge changes from a
named commit to the current branch. - \texttt{git\ pull} - Fetch and
merge changes from a remote repository. - \texttt{git\ push} - Push
changes to a remote repository.

\subsubsection{More on git}\label{more-on-git}

Interested in learning more about git? Here's a free book that teaches
you everything about git and how to use it at a professional level.
Available as both HTML and PDF download:
\href{https://git-scm.com/book/en/v2}{Git Pro}.

\subsection{GitHub - The collaborative
platform}\label{github---the-collaborative-platform}

GitHub is a web-based platform that hosts Git repositories and provides
collaboration tools for developers. It allows developers to share code,
track issues, and collaborate on projects with other developers. GitHub
is widely used for open-source projects, team collaboration, and code
hosting. \#\#\# GitHub Features - Remote Repository Hosting - GitHub
allows you to host projects and code remotely on their servers. - Issues
- Issues are used to track bugs, feature - Pull Requests - Internal
request system for contributors to request code to be pulled. \#\#\#
Workflow Depending on the size of the project and whether the project is
closed- or open-source, the workflow of the project will differ. In this
section we cover some git workflow models and the model you're going to
be using for this course.

\textbf{Centralized}: The project has only one central hub or
\emph{repository}, can accept code and everybody synchronizes their work
with it. This model is suitable for small and closed-sourced projects.
\includegraphics{figures/git_workflow_centralized.png}

\textbf{Integration-Manager:} There are multiple public variants of the
code original code known as \emph{forks}. The integration manager can
decide what features to pull from the forks. This is the model that is
similar to the one used on GitHub
\includegraphics{figures/git_workflow_int_manager.png}

\textbf{Dictator and Lieutenants Workflow:} This is similar to the
integration-manager model, however due to the size of the project. A
rank of integration managers is formed. one example of this is the
development of the Linux kernel.
\includegraphics{figures/git_workflow_dictator.png}

GitHub is designed around a particular collaboration workflow, centered
on Pull Requests. This flow works whether you're collaborating with a
tightly-knit team in a single shared repository, or a
globally-distributed company or network of strangers contributing to a
project through dozens of forks. It is centered on the Topic Branches
workflow covered in Git Branching.

Here's how it generally works: 1. Fork the project. 2. Create a topic
branch from master. 3. Make some commits to improve the project. 4. Push
this branch to your GitHub project. 5. Open a Pull Request on GitHub. 6.
Discuss, and optionally continue committing. 7. The project owner merges
or closes the Pull Request. 8. Sync the updated master back to your
fork.

\subsubsection{Terms}\label{terms}

\begin{itemize}
\tightlist
\item
  Pull Request - A \emph{pull request} is a request to merge changes
  from a feature branch into the main branch or from a forked repository
  to the original or ``upstream'' repository.
\item
  Merge - A \emph{merge} combines the changes from one branch into
  another branch.
\item
  Conflict - A \emph{conflict} occurs when Git cannot automatically
  merge changes and requires manual intervention.
\end{itemize}

\subsubsection{Code resource - Using GitHub to re-use existing
code.}\label{code-resource---using-github-to-re-use-existing-code.}

In your engineering career, you will most likely use a computation
method that has been come up with before. In such scenarios, open-source