8 | -
11 |
- DIME 12 |
- the-world-bank 13 |
- dime-worldbank 14 |
- wb_research 15 |
|
7 |
8 | |
9 |
10 |
|
17 |
58 |
59 | Another example of a type of folder where the clone should not be stored
60 | is a folder that is managed remotely by someone else, such as an IT department.
61 | It is common that you have one or several folders like this if
62 | your computer belongs to a large organization you are working for.
63 | Your access to this folder can change with little notice
64 | and you might therefore lose access to your clone.
65 | An almost universal convention across IT departments in most organizations
66 | is that your user folder in the path `C:\Users\` (Windows) or `/Users/` (Mac)
67 | is a folder you will always have access to.
68 | That is another reasons why `C:\Users\username\github`
69 | or `/Users/username/github` are excellent locations for all your clone.
70 |
71 | ## How do I move a clone on my computer?
72 |
73 | There are two methods we recommend to move a clone on your computer.
74 | Method 1 is easiest but can only be done in some special circumstances.
75 | Method 2 can always be used.
76 |
77 | #### Method 1: Re-clone
78 |
79 | ##### M1: Important - read first
80 |
81 | **Important**: When using this method you will lose anything not committed to GitHub.com.
82 | If you are unsure if that is acceptable in your case, use method 2.
83 | Content that **will be lost** when using this method includes:
84 | * Edits not yet first committed and then also pushed to GitHub.com
85 | * Any files ignored in your `.gitignore` file
86 | * Empty folders or folders with only ignored files
87 |
88 | Example of cases this method is appropriate to move clones on your computer includes:
89 |
90 | * Immediately after the clone was first cloned before any work has been done
91 | * A clone of a repository you never make any edits to,
92 | such as an open source tool you use in your code without editing it first
93 |
94 |
95 | ##### M1: How to move the clone
96 |
97 | In this method you simply delete the clone and clone the repository again.
98 | When deleting the clone it is important that you delete the full folder.
99 | This means that if your repository is called `lyrics-clone`
100 | then you should delete the folder called `lyrics-clone` and all its content.
101 |
102 | If you open GitHub Desktop and select this repository as your current repository,
103 | then you will see the screen shown in the image below.
104 | Then simply click the button "_Clone Again_".
105 | If you do not see this screen or
106 | if you are not able to select the repository as current repository,
107 | then just go to GitHub.com and clone it again.
108 |
109 | 
110 |
111 | This method can also be used if you have some issues with a clone
112 | you know that you have no un-committed/pushed and no ignored files and
113 | and want to start over fresh.
114 | And in this case you can of course clone to the same location.
115 |
116 | #### Method 2: Move the existing clone
117 |
118 | If you want to move the clone and keep all content,
119 | including content not pushed to GitHub.com
120 | such as un-committed edits and ignored files,
121 | then you need to use this method.
122 |
123 | ###### M2: How to move the clone
124 |
125 | First start by copying the clone folder to the new location.
126 | Remember that you need to copy the folder and not just its content.
127 | If you have a repository called `lyrics-clone`,
128 | then you need to copy the clone folder with that name as well as all its content.
129 |
130 | Once you have completed the move of the clone folder, then open GitHub Desktop.
131 | Make sure that you have the repository of the clone you are moving
132 | selected as current repository.
133 | Then you should see the view in the first image below.
134 | Simply click the "_Locate_" and go to the new location of the clone.
135 | Remember to select the clone folder in this step,
136 | and not just the content of the clone.
137 | In the example we have used,
138 | this means that you should select the folder called `lyrics-clone`.
139 | See the second image below.
140 |
141 |
142 |
143 | 
144 |
145 | If you do not see the screen where you are asked to locate the clone,
146 | then go to the menu of GitHub Desktop and select "_File_" -> "_Add local repository_".
147 | Then use the menu that comes up and select the clone folder in the new location.
148 | GitHub desktop will then identify this is the new location of the same clone,
149 | and it will detect that this is a clone of a repository hosted on GitHub.com.
150 |
151 | ## Why are synced folders a bad location for my clone?
152 |
153 | In short, syncing software and git are both collaboration tools,
154 | but they work very differently.
155 | And neither of the tools are implemented to work together,
156 | which can cause many different types of weird errors.
157 |
158 | #### Shared synced folders
159 |
160 | Putting a clone in a shared synced folder quickly leads to issues if
161 | more than one person is expected to work on the same clone in that shared folder.
162 | For example, if one user changes branch in the middle of someone else running the code,
163 | then all weird errors will happen as the files are changed by git.
164 | It is probably easy to see how this leads to errors
165 | and there is no standard workflow where this should ever be the norm.
166 |
167 | #### Non-shared synced folders
168 |
169 | What about non-shared synced folders? Then there will never be an issue with another user.
170 | While that is true, there are still errors than can happen in any kind of synced folder.
171 | And while these errors are more rare they are
172 | likely to cause major disruptions when they happen.
173 |
174 | When syncing software detects a file with edits to be synced to the cloud,
175 | it blocks access to that file for a fraction of a second.
176 | That is fine when it is only much slower humans that also competes for access to those files.
177 | However, git is not a human and in certain git actions,
178 | git can make many updates in a fraction of a second
179 | to the technical files in the `.git` folder.
180 | There is always a `.git` folder in all clone folders,
181 | but depending on the settings of your computer,
182 | this `.git` folder might or might not be visible to you.
183 |
184 | As you use different features of GitHub Desktop,
185 | series of git commands are executed in the background in rapid succession.
186 | This means that git might do an edit to a file,
187 | then do something else and then need to make a second edit to that first file.
188 | This can happen within the same fraction of a second under which
189 | a syncing software has blocked of access to the file.
190 | Sometimes this is fine, other times GitHub Desktop tells you there is an error,
191 | but sometimes there is an error in these files that is not detected immediately.
192 |
193 | This can lead to things like git not being aware that you have changed branch
194 | and commits you think you are committing to one branch,
195 | are actually pushed to a different branch.
196 | This is difficult enough to solved if identified early on,
197 | but it has happened in DIME projects that nothing was detected
198 | until it was pushed to GitHub.com and someone else tried to pull the same edits.
199 |
200 | Those errors can be as weird as according to GitHub Desktop,
201 | you are committing to one branch,
202 | thought what is really happening in the `.git` folder is that
203 | you are actually committing to some other branch.
204 | This will create weird conflicts that are difficult to solve.
205 | Sometimes the easiest way of solving such issue is to delete those commits
206 | and re-do all the work since the error happened.
207 | Since the error might have been undetected for a while,
208 | this could mean weeks or months of lost work.
209 |
210 | Again, these errors are rare but they have happened a couple of time at DIME,
211 | but since the best practice is so easy to follow,
212 | we should all remember to not put our clones in synced folders.
213 |
--------------------------------------------------------------------------------
/GitHub-trainings/github-team-maintainer-training/latex-slides/github-team-maintainer-training.tex:
--------------------------------------------------------------------------------
1 | % ---------------------------- Preamble starts here ----------------------------
2 |
3 | \documentclass[aspectratio=169]{beamer} %Remove [aspectratio=169] to get non-wide 4:3 slide aspect ratio
4 |
5 | %-----------------------------------------------
6 | % --- Set beamer theme
7 | \usetheme{Metropolis}
8 | \setbeamertemplate{footline}{} % Remove automatic footer
9 | \setbeamertemplate{navigation symbols}{} % Comment this line to display navigation symbols
10 |
11 | %-----------------------------------------------
12 | % Load i2i symbol
13 | \addtobeamertemplate{frametitle}{}{%
14 | \begin{textblock*}{\linewidth}(0cm,7.1cm) % Replace with (0cm, 8cm) if using non-wide slide aspect
15 | \includegraphics[width=\linewidth]{../../Common-Resources/img/Footer.png}
16 | \end{textblock*}}
17 |
18 | %-----------------------------------------------
19 | % --- Load packages
20 | \usepackage{textpos} % To align objects correctly
21 | \usepackage{multicol} % To right in multiple columns
22 | \usepackage{color} % To color text
23 |
24 | %-----------------------------------------------
25 | % --- Include link to last commit
26 | \usepackage{xstring}
27 | \usepackage{catchfile}
28 |
29 | %Set this user input
30 | \newcommand{\gitfolder}{../../../.git} %relative path to .git folder from .tex doc
31 | \newcommand{\reponame}{worldbank/dime-github-trainings} % Name of account and repo be set in URL
32 |
33 | %Based on this https://tex.stackexchange.com/questions/455396/how-to-include-the-current-git-commit-id-and-branch-in-my-document
34 | \CatchFileDef{\headfull}{\gitfolder/HEAD.}{} %Get path to head file for checked out branch
35 | \StrGobbleRight{\headfull}{1}[\head] %Remove end of line character
36 | \StrBehind[2]{\head}{/}[\branch] %Parse out the path only
37 | \CatchFileDef{\commit}{\gitfolder/refs/heads/\branch.}{} %Get the content of the branch head
38 | \StrGobbleRight{\commit}{1}[\commithash] %Remove end of line characted
39 |
40 | %Build the URL to this commit based on the information we now have
41 | \newcommand{\commiturl}{\url{https://github.com/\reponame/commit/\commithash}}
42 |
43 | %-----------------------------------------------
44 | % --- Add your information here
45 | \title{An intro to Git and GitHub - Team Maintainer}
46 | \author{DIME Analytics}
47 | \institute{DIME - The World Bank - \trainingURL{https://www.worldbank.org/en/research/dime}}
48 | \date{\today}
49 |
50 | \newcommand{\trainingURL}[1]{{\color{blue}\url{#1}}}
51 |
52 | \newcommand{\traininerUsername}{kbjarkefur}
53 | \newcommand{\repoName}{\traininerUsername/lyrics-Jun17}
54 | \newcommand{\trainingRepoURL}[1]{\trainingURL{github.com/\repoName #1}}
55 | \newcommand{\trainerEmail}{\trainingURL{kbjarkefur@worldbank.org} }
56 |
57 |
58 | % ---------------------------- Preamble ends here ----------------------------
59 |
60 | \begin{document}
61 |
62 | \begin{frame}
63 | \includegraphics[width=\textwidth]{../../Common-Resources/img/Header.png}
64 | \vspace{-0.2cm}
65 | \titlepage % Opening slide, prints inform
66 | \end{frame}
67 |
68 | \begin{frame}
69 | \frametitle{Objectives}
70 |
71 | This is the topics that we will cover in this training:
72 | \begin{itemize}
73 | \item Why do we bother with teams?
74 | \item Quick guide to how to do team maintainer tasks
75 | \item What other tasks do we ask the team maintainers to help us with?
76 | \end{itemize}
77 | \end{frame}
78 |
79 |
80 | \begin{frame}
81 | \frametitle{Quick role overview}
82 |
83 | \begin{columns}[T]
84 |
85 | \column{.15\textwidth} % Left buffer
86 |
87 | \column{.30\textwidth} % Left column and width
88 | \textbf{Repo roles:}
89 | \begin{itemize}
90 | \item Contributor
91 | \item Repo Maintainer
92 | \item Repo Admin
93 | \end{itemize}
94 |
95 | \column{.10\textwidth} % Middle buffer
96 |
97 | \column{.30\textwidth} % Right column and width
98 | \textbf{Team roles:}
99 | \begin{itemize}
100 | \item Member
101 | \item Team Maintainer
102 | \end{itemize}
103 |
104 | \column{.15\textwidth} % Right buffer
105 |
106 | \end{columns}
107 | \end{frame}
108 |
109 |
110 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
111 | %% Why bither with teams?
112 |
113 | \section{Overview and work flow}
114 |
115 | \begin{frame}
116 | \frametitle{Objectives}
117 |
118 | \begin{itemize}
119 | \item As default we do not give the project teams admin access to the repos
120 |
121 | \item With admin access you can do potentially destructive actions -- such as deleting the whole repo and all its history.
122 |
123 | \item We still want you to give access to the teams to add and remove users from the repo without having to ask DIME Analytics each time.
124 |
125 | \item On GitHub, Teams can be used to control access to repos without giving admin access
126 |
127 | \end{itemize}
128 | \end{frame}
129 |
130 | \begin{frame}
131 | \frametitle{GitHub Teams Creation Work Flow}
132 |
133 | \begin{columns}[c]
134 |
135 | \column{.60\textwidth} % Left column and width
136 | \begin{enumerate}
137 | \item DIME Analytics creates a team
138 | \item DIME Analytics makes one team member the \textit{team maintainer}
139 | \item DIME Analytics creates a repo and adds the team to the repository
140 | \item The team maintainer add and remove user to the team to grant and revoke access to the repo
141 | \item Only users added to the DIME organization account can be added to teams
142 | \end{enumerate}
143 |
144 | \column{.40\textwidth} % Right column and width
145 | \begin{figure}
146 | \centering
147 | \includegraphics[width=1\linewidth]{./img/teams-workflow}
148 | \end{figure}
149 |
150 | \end{columns}
151 | \end{frame}
152 |
153 |
154 | \begin{frame}
155 | \frametitle{Quick talking points}
156 |
157 | \begin{columns}[c]
158 |
159 | \column{.50\textwidth} % Left column and width
160 | Quick facts about teams:
161 | \begin{itemize}
162 | \item There can be more than one team maintainer for a team
163 | \item A team can be used for more than one repo
164 | \item A repo can have more than one team added to it
165 | \end{itemize}
166 |
167 | \column{.50\textwidth} % Right column and width
168 | Admin access vs. Teams
169 | \begin{itemize}
170 | \item Can I be made admin instead of dealing with teams?
171 | \item Sure, but we will ask for the TTL's approval to do so after explaining to them the risks associated with admin access
172 | \end{itemize}
173 |
174 | \end{columns}
175 | \end{frame}
176 |
177 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
178 | %% Quick overview how to do things
179 |
180 | \section{How to do Team actions on GitHub.com}
181 |
182 | \begin{frame}
183 | \frametitle{Which teams am I in?}
184 | \textbf{How do I know which teams I am in?}
185 | \begin{enumerate}
186 | \item Go to \url{https://github.com/dime-worldbank} and click \textit{Teams}
187 | \item Then search for your username, like \textit{@username}
188 | \end{enumerate}
189 | \centering
190 | \includegraphics[width=.8\linewidth]{./img/which-teams-am-i-in}
191 | \end{frame}
192 |
193 |
194 | \begin{frame}
195 | \frametitle{Am I a team maintainer for a team?}
196 | \begin{columns}[c]
197 |
198 | \column{.30\textwidth} % Left column and width
199 | \textbf{Check who is team maintainer:}
200 | \begin{enumerate}
201 | \item Click the team name
202 | \item Click \textit{Members}
203 | \item See who has the \textit{Maintainer} sticker
204 | \end{enumerate}
205 |
206 | \column{.70\textwidth} % Right column and width
207 | \begin{figure}
208 | \centering
209 | \includegraphics[width=1\linewidth]{./img/who-is-team-maintainer}
210 | \end{figure}
211 | \end{columns}
212 | \end{frame}
213 |
214 |
215 | \begin{frame}
216 | \frametitle{How do I manage team members?}
217 | \begin{columns}[c]
218 |
219 | \column{.30\textwidth} % Left column and width
220 | \textbf{Add user:}
221 | \begin{enumerate}
222 | \item Click \textit{Add a member}
223 | \item Enter new members username
224 | \end{enumerate}
225 |
226 | \textbf{Remove user:}
227 | \begin{enumerate}
228 | \item Check the check box next to user
229 | \item Select \textit{Remove from team} in the menu that appears above the list of memebers
230 | \end{enumerate}
231 |
232 |
233 | \column{.70\textwidth} % Right column and width
234 | \begin{figure}
235 | \centering
236 | \includegraphics[width=1\linewidth]{./img/who-is-team-maintainer}
237 | \end{figure}
238 | \end{columns}
239 | \end{frame}
240 |
241 |
242 | \begin{frame}
243 | \frametitle{Which repos is a team used for?}
244 | \textbf{Which repos are a team used for?}
245 | \begin{enumerate}
246 | \item In the team page, click \textit{Repositories}
247 | \end{enumerate}
248 | \centering
249 | \includegraphics[width=.8\linewidth]{./img/which-repos-in-team}
250 | \end{frame}
251 |
252 |
253 | \begin{frame}
254 | \frametitle{Which teams are used for a repo?}
255 | \begin{columns}[c]
256 | \column{.30\textwidth} % Left column and width
257 | \textbf{Which teams in used in a repo?}
258 | \begin{enumerate}
259 | \item Go to \url{https://github.com/worldbank/dime-github-admin}
260 | \item Click reports, then click your repo
261 | \item Scroll down to collaborators and check the columns
262 | \end{enumerate}
263 |
264 | \column{.70\textwidth} % Right column and width
265 | \begin{figure}
266 | \centering
267 | \includegraphics[width=1\linewidth]{./img/which-teams-in-repo}
268 | \end{figure}
269 | \end{columns}
270 | \end{frame}
271 |
272 |
273 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
274 | %% Other tasks
275 |
276 | \section{Other tasks involving team maintainers}
277 |
278 | \begin{frame}
279 | \frametitle{Other tasks involving team maintainers}
280 |
281 | \begin{itemize}
282 | \item We will use the team maintainer as the contact person for repos linked to a team
283 |
284 | \item If admins have a question about a repo, then we will contact the team maintainer/maintainers for the team/teams linked to that repo. The team maintainer does not need to know all answers, but should at least know who to talk to
285 |
286 | \item Whenever admins are performing a large scale process, such as a transfer, we will turn to team maintainers for help
287 |
288 | \end{itemize}
289 | \end{frame}
290 |
291 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
292 | %% Transfer
293 |
294 | \section{Transfer to dime-worldbank account}
295 |
296 | \begin{frame}
297 | \frametitle{dime-worldbank account set up}
298 |
299 | \begin{itemize}
300 | \item In the new account we have an unlimited number of private and public repositories, but instead we pay for users.
301 | \item We pay for all users added to the the organization account.
302 | \item We pay for external collaborators added private repositories, but not for public repositories.
303 | \item DIME Analytics covers this cost for the foreseeable future, in return we just ask the team maintainers to help us remove people as they leave.
304 | \end{itemize}
305 | \end{frame}
306 |
307 |
308 | \begin{frame}
309 | \frametitle{Team maintainers tasks on transfer}
310 |
311 | \begin{enumerate}
312 | \item Check that all team members are still current members
313 | \item Check that all external collaborators for all repos the team is used for are still current users
314 | \item Decide if public repos should be transferred or not
315 | \item Help us communicate to the team. We provide a template for that communication, but it is better if it comes from you
316 | \end{enumerate}
317 |
318 | If you are interested, see our full transfer protocol here: \url{https://github.com/dime-worldbank/dime-account-admin-private/blob/master/transfer-from-old-account/README.md}
319 | \end{frame}
320 |
321 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
322 | %% Discussion
323 |
324 | \section{Discussion}
325 |
326 | \begin{frame}
327 | \frametitle{Discuss best practices}
328 |
329 | \begin{itemize}
330 | \item Big teams for many repos or one small team per repo?
331 | \item A team maintainer should know of the repos a team is used for but does not need to work on the projects for those repos
332 | \item Multiple team maintainer in one team?
333 | \item Give admin access to the research team?
334 | \item Other questions to discuss?
335 | \end{itemize}
336 |
337 | \end{frame}
338 |
339 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
340 | %% End boiler plate
341 |
342 | \section{Links}
343 |
344 | \input{../../Common-Resources/slides/GitHub-Links.tex}
345 |
346 | \input{../../Common-Resources/slides/GitHub-Commit-URL.tex}
347 |
348 |
349 | \end{document}
350 |
--------------------------------------------------------------------------------