cedrict
commented
9 years ago Hi, Here is a 3-page document that tries to remedy a lack of informations in the manual with regards to how to contribute to ASPECT (code, manual, tests, benchmarks, ...) and how to interface with git. This is based on Anne's extensive personal notes. It would be nice if one of you could review it, make sure that what is in there is sound, add whatever you feel is still missing. It could be either part of the manual, in the appendix, or an external document hosted on the website. Or simply a webpage ? Cheers,
C.
\documentclass[a4paper]{article}
\usepackage{fullpage}
\begin{document}
Here is a document that tries to remedy a lack of informations in the manual with regards to how to contribute to ASPECT (code, manual, tests, benchmarks, ...) and how to interface with git. Author: A. Glerum
I think it would be great to have W's picture with the 4 blobs, subdivided into remote and local.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Obtaining ASPECT for the first time}
\begin{enumerate}
\item Create an account on GitHub.com
\item On GitHub, fork the official ASPECT repository to your repository
\item On your machine, set up your identity: \$ \verb"git config --global user.name ``Your Name''" and \$ \verb"git config --global user.email your@email"
\item On your machine, clone your repository with \$ \verb"git clone http://address_of_your_repository", this is now your master branch
\item On your machine, find your security key \footnote{
Note that you can create a public key as follows:
{\tt https://help.github.com/articles/generating-ssh-keys/}}
with \$ \verb"less ~/.ssh/id_dsa.pub" and copy this into GitHub so you can push to your repository \item Also create a remote of the official version with \$ \verb"git remote add upstream http://address" \verb"_of_ASPECT" \end{enumerate}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{How to contribute ASPECT}
Let us assume that you have written a new plugin, say 'myplugin.cc' that is in the {\sl source/mesh_refinement} folder and that you wish to share it with us all.
\begin{enumerate} \item \textbf{On the master branch}, \$ \verb"git pull upstream master" - to update the master branch from the CIG repository \item Followed by \$ \verb"git push origin master "- to update your repository on GitHub
\item You first need to make a new branch: \$ \verb"git branch branchformyplugin"
\item You then need to switch to this branch: \$ \verb"git checkout branchformyplugin"
\item Note that the last two commands could have been carried out in one go as follows:\ \$ \verb"git checkout -b branchformyplugin" (this creates and switches to the new branch)
\item Type \$ \verb"git branch" to verify that the star is now positioned in front of branchformyplugin.
\item You then need to add the files that you have modified. In our case, this is a plugin, so two files only: \begin{verbatim} git add include/aspect/mesh_refinement/myplugin.h git add source/mesh_refinement/myplugin.cc \end{verbatim} This specifies which files you want to commit.
\item You then need to commit it and give it a 'message': \begin{verbatim} git commit -m "new plugin for bla bla" \end{verbatim} You can ommit the \verb"-m" but a window will then open a require you to type a message.
\item \$ \verb"git push origin branchformyplugin" - this will push the branch to your repository \end{enumerate}
\begin{list}{}{} \item It is good practice to commit and push your changes even when you are not done yet, this serves as a back-up \item Make sure commit message is in present tense (e.g. Fix some typos) \item When finished, on GitHub, go to the corresponding branch and "create pull request" \item If the branch contains a new functionality in the code, make sure to add something to {\sl doc/modules/changes.h} \item Possible comments of Timo or Wolfgang are shown on GitHub, where they can also be commented on by you \item When you push improved code after having created the pull request, the request is automatically updated \end{list}
Write something about how to contribute to manual.
\subsection{Branch management}
If you wish to try an idea, you can create a branch to try it out, say 'experimental'
\begin{verbatim} git branch experimental git checkout experimental \end{verbatim}
At this point you could delete the experimental branch with \begin{verbatim} git branch -d experimental \end{verbatim} This command ensures that the changes in the experimental branch are already in the current branch. If you develop on a branch crazy-idea, then regret it, you can always delete the branch with \begin{verbatim} git branch -D crazy-idea \end{verbatim}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Useful commands} \begin{list}{}{} \item \$ \verb"git remote -v" - this lists your remote repositories (should include geodynamics) \item \$ \verb"git log" - this lists the commits in reverse chronological order (see also \ref{log}) \item \$ \verb"git branch" - this lists all your branches; the current branch will have an asterisk in front of its name \item \$ \verb"git branch -d name_of_existing_branch" - deletes the given branch (will only work if you're not on this branch and the commits in the branch are merged in another branch) \item \$ \verb"git checkout name_of_existing_branch" - switches to the given branch; this will only work when all changed files have been committed \item \$ \verb"git status "- shows the changes of the branch; gives untracked files or changes that should be committed \item \$ \verb"git config --list" - shows all your settings \item \$ \verb"git diff" - lists the exact difference between your working file and the staged file \item \$ \verb"git diff --staged" - lists the exact difference between the staged file and the committed file \item \$ \verb"git rm file_name" - this will remove the file from the staging area and from your working directory (really deletes the file) \item \$ \verb"git rm --cached file_name" - this will remove the file from the staging area \item \$ \verb"git mv old_file_name new_file_name" \item \$ \verb"git reset HEAD file_name" - to unstage a file \item \$ \verb"git checkout -- file_name" - overwrites your current file with the last committed one!! \item \$ \verb"git fetch remote_name" - fetches all data in remote repository that you don't have yet; merging it is left to you (as opposed to git pull) \item \$ \verb"git tag" - shows the tags in the repository (for example, the releases are tagged) (use -a tag_name to create an annotated tag, just tag_name for a lightweight tag) \item \$ \verb"git config --global alias.some_alias 'some_command'" - set up git alias \item \$ \verb"git branch new_branch_name" - creates a branch, but does not switch to it4 \item \$ \verb"git cherry-pick commit_nr" - apply the changes of the single commit \item \$ \verb"gitk" - visual display of history \item \$ \verb"git log -p" - also provides the diff between commits \item \$ \verb"git log -2" - shows only last 2 commits (always per page anyway) \item \$ \verb"git log -U1 --word-diff" - as normal log, but only 1 line of context and only inline word diffs \item \$ \verb"git log --pretty=oneline" - print log info one line per commit (short, full, fuller and format also possible) \item \$ \verb"git log--graph" - also show ASCII graph of branch and merge history \item \$ \verb"git log--since=2.weeks" \item \$ \verb"git log--until=some_date" \item \$ \verb"git log--author=name_author" \item \$ \verb"git log--grep=some_word" - searches for some_word in commit message (when using multiple greps, also state --all-match) \item \$ \verb"git remote show remote_name" - gives info on remote \item \$ \verb"git remote rename old_name new_name" - rename remote \item \$ \verb"git remote rename remote_name" - remove remote \end{list}
\subsection{You've messed up your local master branch} If your own remote master (called origin/master in my case) is still a pristine copy of the geodynamics/aspect remote repository, so you haven't pushed your messed up master to it, do the following: \begin{enumerate} \item git reset --hard origin/master \item git pull geodynamics master \item git push origin master \end{enumerate} The first command resets your local master branch to the pristine, but old, state of your remote master. Then git pull updates your local master (should be fast-forward) and then you push this to your remote master. Now both your local and remote master are up to date!
\subsection{Your older branch needs new edits that are in master} If you've got a branch from master called, let's say, ``instantaneous'', and you find some issue that you report and it is fixed by the developers: \begin{enumerate} \item git pull geodynamics master \item git push origin master \item git checkout instantaneous \item git merge master or git rebase master \end{enumerate}
\subsection{You've committed and pushed a change that you never should have}
\begin{enumerate}
\item \verb"git reset --hard HEAD~1" (only removes last commit)
\item make some changes
\item \verb"git add
\newpage %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{How to contribute a test}
describe here philosophy of tests.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{How to contribute a benchmark}
\newpage
What does this do and when to do it:
\begin{verbatim} git remote add upstream git@github.com:geodynamics/aspect.git \end{verbatim}
Help:
http://git-scm.com/docs/gittutorial
http://rogerdudler.github.io/git-guide/
http://lifehacker.com/5983680/how-the-heck-do-i-use-github
\end{document}
bangerth
Should include adding something to changes.h