\documentclass[noanswers,addpoints,11pt]{exam}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage[most]{tcolorbox}
\usepackage{datetime}
\usepackage{enumerate}
\usepackage{xltxtra}
\usepackage{listings}

\usepackage{graphicx}
\usepackage{hyperref}
\usepackage{makecell}
\usepackage{multicol}
\usepackage{multirow}

\usepackage{tabularx}
\usepackage{textcomp}
\usepackage{tikz}
\usetikzlibrary{arrows,automata,decorations.pathmorphing,backgrounds,positioning,fit}
\usepackage{pgf-umlcd}

\usepackage{fontspec}
%\setmainfont{Gentium Basic}
%\setmonofont{Comic Code}[
%Scale          = 0.80,
%UprightFont    = *-Regular,
%ItalicFont     = *-Italic,
%BoldFont       = *-Bold,
%BoldItalicFont = *-Bold Italic
%]
%\lstset{
%  basicstyle=\ttfamily,
%}

\newcommand{\checkpoint}{{\Large $\checkmark$} }

% classname
\newcommand\examNumber{CIS 405 Software Engineering: Assignment p01, Gitea Setup}
\newcommand\semester{Spring 2024}
\newcommand\className{Software Engineering}
\newcommand\classNumber{CIS~405}
\newcommand\classFullName{\classNumber~\className}
\renewcommand{\dateseparator}{-}
\yyyymmdddate

% /classname

\pagestyle{headandfoot}
\firstpageheader{\classNumber\\\semester}{\examNumber\\~}{\today\\~}
\runningheader{\examNumber}{}{\today}

\newenvironment{showExample}[1]{
  \begingroup
  \renewcommand{\solutiontitle}{\noindent\textbf{Example:}\enspace}
  \printanswers
  \begin{solution}[#1]
  }{
  \end{solution}
  \endgroup
}

\definecolor{outputgray}{gray}{0.9}

\newcommand\org{S24-405}
\newcommand\repo{p01-GiteaSetup}
\newcommand\organization{\texttt{\org}}
\newcommand\repository{\texttt{\repo}}
\begin{document}
\pointsinrightmargin{}

\section*{Learning Outcomes}

After completing this lab, a student will be able to
\begin{enumerate}
\item \textbf{Log in} to the \emph{Gitea} server on
  \texttt{cs-devel.potsdam.edu} with a new password they picked.
\item Find the \organization{} course organization where class source
  code will be distributed.
\item \textbf{Clone} a specific repository from the server
  using \texttt{git} on a CS lab computer.
  \item Create organizations, teams, and repositories in \texttt{Git}.
\item Do simple management of a \texttt{Git} repository.
\end{enumerate}

\section*{Deliverables}
There are two (2) deliverables for this assignment:
\begin{enumerate}
\item \texttt{README} file in an acceptable plain-text format (\texttt{.md, .txt, .org})
\item \texttt{HelloWorld.java}
\end{enumerate}
Submission is through the CS Department Gitea.
\section*{Introduction}

\subsection*{Overview}
Git is an essential tool for developing software as part of a team. Even if you have used Git as an individual developer, in this course you will learn more complex skills, such as resolving merge conflicts, that support source code versioning with multiple developers.

If you have used Git and the CS Gitea server before, you can skip to the next section. If you are new to Git or Gitea, continue reading ``Square One''.

\subsection*{Square One}
\texttt{git} is a \emph{version control} program. You can think of
it like a database of changes across some set of text files. It is
designed to keep track of changes to a \textbf{set} of files over
\textbf{time} and make sharing the versions of those files easy.

It is designed to handle any number of files, from the Java code used
during a single lab section up to \textbf{all} of the Linux operating
system kernel (so, tens of lines of code in a handful of files up to
tens of \emph{millions} of lines of code across thousands of
files). In this class you will use \texttt{git} (a program running
on your local machine) to connect to a server running
on \texttt{cs-devel.potsdam.edu} to download \emph{sample code}, helper code for
\emph{assignments}, and eventually as part of the team software project.


\section*{Using \texttt{git}}
If you're new to the CS Department Gitea server, your account has been set up with a dummy password. You will log
in to the server, find the \emph{repository} (the \texttt{git} term
for a set of files) associated with this assignment, copy the link for the
\emph{repo}, and download it locally.

\begin{questions}
\question{} \textbf{(New Gitea users)} Change your \emph{password} on the \emph{Gitea} server
  on \texttt{cs-devel.potsdam.edu}.

  Point your browser at \url{https://cs-devel.potsdam.edu}. Your login
  name is the same as your Potsdam email address
  \emph{without} \texttt{@potsdam.edu}. If you haven't used Gitea in the past, your password
  is \texttt{Kil0Ech0} (note the capitalization and use of
  digits). Because everyone with a new Gitea account has the same password, the
  first step is to change it.

  Once you login, your Dashboard will be displayed. A randomly
  generated avatar image for you is shown in the upper-right of the
  screen. Clicking on it gives a drop down menu
  including \texttt{Settings}. Select \texttt{Settings}.

  Your profile is shown with a horizontal menu across the top of then
  page. Find the \texttt{Account} entry, click on it, and the top
  of that page is a form to change your password. Change the password
  (it is \textbf{not} connected to your standard campus account so it
  will not change that password nor will changing the campus password
  change this one). Click the \texttt{Update Password} button when
  you have entered a password you will remember.

  \checkpoint{} Be sure that you can log \emph{out}
  and then log back \emph{in} to the \emph{Gitea} server with your new
  password.

\question{} Your newly logged in to Dashboard is pretty empty but
  there is a pair of tabs near the center top,
  labeled \texttt{Repositories}
  and \texttt{Organizations}. Initially \texttt{Repositories} is
  selected. Click on \texttt{Organizations}.

  You were added to the \organization{} organization as an existing user or when your account
  was created. That organization is where the
  instructor will distribute source code. You are a member of
  the \texttt{Student} team in the organization, so you can read
  the contents but not change them. Click on the \organization{} link.

  You should now see the \repository{} repo (along with any other
  repositories that have been posted to the class; this is where you
  are going to go to get source code that is distributed to the class and any code materials for assignments. Click on the \repository{} link.

  Finally, you are on the page for \organization{}/\repository{}. The
  repository shows the files and folders on this page. Just above the
  listing of the contents is a bright line. Below the right end of the
  line is a box with an URL in it, an URL beginning
  with \texttt{https://cs-devel.potsdam.edu} and so on. To the
  right of the text box is a copy icon; click on the copy icon to copy
  the URL to the clipboard. That URL is how the \texttt{git}
  program will find the repository to copy onto your local machine.

  Open a terminal window on the local machine. Navigate to the folder
  where you want to download the repo (a new subfolder will be created
  with the repo contents). Assume I want \repository{} copied into
  the \texttt{~/CIS405} folder. In that folder I would
  type \texttt{git clone}, a space, and then I would paste the URL
  copied above. Like this:


\begin{lstlisting}[backgroundcolor=\color{outputgray},escapechar=*]
~ $ cd CIS405
~/CIS405 $ git clone https://cs-devel.potsdam.edu/*\org{}/\repo{}*.git

Cloning into '*\repo{}*'...
Username for 'https://cs-devel.potsdam.edu': grabowlm
Password for 'https://grabowlm@cs-devel.potsdam.edu':
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.

~/CIS405 $
\end{lstlisting}

  Hitting enter at \texttt{git clone} will prompt for your account name and
  password on the \emph{Gitea} server and will then create a subfolder
  named \repository{} below the current directory containing the
  contents of the repo. Note that the exact number of objects will
  differ depending on the repository being cloned.

  \checkpoint{} Ensure that you have successfully cloned the repo to your local machine.

\section*{Background for handin through \texttt{git}}
The following Gitea help videos are available to you at any time:
%
%    "Creating a Gitea Organization for Turnin":  http://cs.potsdam.edu/Classes/git-videos/CreatingAGiteaOrganizationForTurnIn.mp4
%    "Create a local repo": http://cs.potsdam.edu/Classes/git-videos/GitCreateLocalRepo.mp4
%    "Git repo turnin": http://cs.potsdam.edu/Classes/git-videos/GitRepoTurnIn.mp4
%    "Clone course source code": http://cs.potsdam.edu/Classes/git-videos/GiteaCloneCourseSourceCode.mp4
\begin{itemize}
\item ``Creating a Gitea Organization for Turnin'',\\ \href{http://cs.potsdam.edu/Classes/git-videos/CreatingAGiteaOrganizationForTurnIn.mp4}{http://cs.potsdam.edu/Classes/git-videos/CreatingAGiteaOrganizationForTurnIn.mp4}
\item ``Creating a local repo'',\\ \href{http://cs.potsdam.edu/Classes/git-videos/GitCreateLocalRepo.mp4}{http://cs.potsdam.edu/Classes/git-videos/GitCreateLocalRepo.mp4}
\item ``Git repo turnin'',\\ \href{http://cs.potsdam.edu/Classes/git-videos/GitRepoTurnIn.mp4}{http://cs.potsdam.edu/Classes/git-videos/GitRepoTurnIn.mp4}
\item ``Clone course source code'',\\ \href{http://cs.potsdam.edu/Classes/git-videos/GiteaCloneCourseSourceCode.mp4}{http://cs.potsdam.edu/Classes/git-videos/GiteaCloneCourseSourceCode.mp4}
\end{itemize}
\section*{Creating and managing a \texttt{git} organization and repository}
%\begin{questions}
\question{} The \texttt{git} version control system has been used
  to distribute class assignments and share source code with the
  class. This has been done through an \emph{organization},
 \organization{}  on the \textbf{Gitea} server running on
  \texttt{cs-devel.potsdam.edu}.

  The organization is a level of administration between the
  \texttt{git} repository (a single project/assignment) and the
  whole shared Departmental server (all the data on
  \texttt{cs-devel}). It can be used to limit access to a
  collection of repositories (``repos'' from here on).

  When you turn in your work using \texttt{git}, you \emph{could}
  put it in a \textbf{public} repo on the server. A public repo can be
  \emph{seen} and \texttt{clone}d by anyone with an account on
  \texttt{cs-devel}. This is \emph{good} because your instructor can
  clone it to grade it; this is \emph{bad} because unscrupulous
  students can clone it to turn it in as their own.

  Creating an organization that \emph{you} own means you can create
  and upload repos in the organization. Adding your instructor to the
  organization with \textbf{read-only} access means that they can see
  and clone \textbf{private} repos owned by the organization. With
  only two members of the organization, only two accounts have access
  to the private repos.

%  The process is outlined in the video\\
%  \href{http://cs.potsdam.edu/Classes/443/video/CreatingAGiteaOrganizationForTurnIn.mp4}{http://cs.potsdam.edu/Classes/443/video/CreatingAGiteaOrganizationForTurnIn.mp4}.

  \begin{parts}
  \part{} Log in to your \emph{Gitea} account on \texttt{cs-devel.potsdam.edu}.
  \part{} Create a new organization named \org-{\texttt{<email>}}
    where \texttt{<email>} is replaced with your campus email
    address (before the \texttt{@} sign). The \textbf{Organization}
    tab is on the dashboard (home) page, to the middle right. There is
    a `+' sign to add a new organization.

    Name your organization as above and make it \emph{private}.
  \part{} Go to your new organization's dashboard page by clicking on
    its name beneath the \textbf{Organization} tab.

  \part{} Create a new \emph{Instructor} team: beneath the list of
    teams, click \textbf{New Team}. Name the new team
    \emph{Instructor} and let them access \textbf{All
      repositories}. You will see the access is \emph{Read} which is
    fine. Finish creating your new team.
  \part{} Add your instructor to your team. On the team page, type the
    instructor's email address into the search bar, select them and
    click the \textbf{Add Team Member} button.
  \end{parts}

\checkpoint{} Return to the \emph{organization} dashboard and check that your organization has two teams and that the two teams that share access.

\question{} You will now create a \emph{repository} owned by the
  \emph{organization} you created in the previous checkpoint. The
  exact process is outlined in\\
  \href{http://cs.potsdam.edu/Classes/git-videos/GitRepoTurnIn.mp4}{http://cs.potsdam.edu/Classes/git-videos/GitRepoTurnIn.mp4}.

  The video outline is:
\begin{verbatim}
* Set configuration values for git
  Set the default branch name to main (instead of master) and set
  the user's email address. The --global means for all repositories
  under this account.

  Remember to replace the "johndoe" with YOUR email address.

  #+BEGIN_SRC bash
    git config --global user.name "John Doe"
    git config --global user.email johndoe@example.com
    git config --global init.defaultBranch main
  #+END_SRC

* Create *local* repository in the directory where you're working
  Empty ~git~ repository for assignment
  #+BEGIN_SRC bash
    git init
  #+END_SRC

* Edit files for assignment
  Write a README file with your ID block in it and assignment information.
  NOT IN THE VIDEO: Write HelloWorld.java to include in your repo. Keep it simple.
  NOT IN THE VIDEO:  Update your README file with compile/run instructions for HelloWorld.java

* Add changed files to local ~git~
  #+BEGIN_SRC bash
    git add .
  #+END_SRC

* Commit changes to local ~git~
  #+BEGIN_SRC bash
    git commit
  #+END_SRC
  Then fill out a commit message.

* Create a *remote* repository on ~cs-devel~
  Login
  Switch to your organization S24-405-johndoe
  Create *empty* repository p01-GiteaSetup
  Use instructions Gitea printed for us to connect
* Loop until done
** Make and commit more *local* changes
** Push *local* changes up to *remote* repo
   #+BEGIN_SRC bash
    git push origin main
   #+END_SRC
\end{verbatim}

  \checkpoint{} Check the repository on the local
  machine and on \texttt{cs-devel}. To check the status of your local repo, run \texttt{git status} and/or
  \texttt{git log}. The \texttt{git status} command should show the following messages:
 \begin{lstlisting}[backgroundcolor=\color{outputgray},escapechar=*]
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean
 \end{lstlisting}
 The command \texttt{git log} will show a message similar to the following:
  \begin{lstlisting}[backgroundcolor=\color{outputgray},escapechar=*]
commit f2bd49d6195fdc61ed03c9bb9ccba8c47e98109c (HEAD -> main, origin/main)
Author: Laura Grabowski <grabowlm@potsdam.edu>
Date:   Sun Jan 21 16:04:25 2024 -0500

    init: README.md
 \end{lstlisting}
 The details will be replaced with the details of your repo (a different commit, your name, the date of the commit, and your commit message).

\question{} Commit changes and push your updated files (\texttt{README} and \texttt{HelloWorld.java} to your Gitea repo for this assignment.

\checkpoint{} Check your Gitea repo to ensure that changes were committed.

\end{questions}



\end{document}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End:
