Contribute.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Programming in julia/Hecke/Oscar - Session 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Contributing to Hecke\n",
    "\n",
    "We will illustrate how to contribute to Hecke. Similar to all other packages that make up Oscar, Hecke is hosted on GitHub (www.github.com).\n",
    "\n",
    "1. Create a GitHub account by followign the instructions on www.github.com.\n",
    "\n",
    "2. Log into your GitHub account and fork Hecke. This is done by navigating to www.github.com/thofma/Hecke.jl and pressing the \"Fork\" button, which can be on the right hand side at the top. See the picture below.\n",
    "![Image Test](fork.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "3. Open julia and run `]dev Hecke`. This will make julia download the master branch of Hecke and at the some time track it. You can check this by running `]st`. It should output something like:\n",
    "```julia\n",
    "(@v1.5) pkg> st\n",
    "Status `~/.julia/environments/v1.5/Project.toml`\n",
    "  ...\n",
    "  [3e1990a7] Hecke v0.9.1 `~/.julia/dev/Hecke`\n",
    "  ...\n",
    "```\n",
    "This tells us that whenever we are doing now `using Hecke`, it will use the version it finds in `~/.julia/dev/Hecke`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "4. Now we can already change our local version and the changes will appear when doing `using Hecke`.\n",
    "> For maximal fun, we should remember to always do `using Revise` first. This means that julia will reload the files we change locally and we can observe the changes live in the REPL.\n",
    "\n",
    "5. OK, we have done some local changes and we would like to contribute them to the official version. This is now an exercise in git."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Using git in the command line\n",
    "\n",
    "There are different ways to use git, including programs with a graphical user interface. Since this is not always available, we consider the most basic way to use git, which is via the command line."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "1. Start julia, do a `]st` and look at directory which is printed next to the entry for Hecke. In our example, this is `~/.julia/dev/Hecke`.\n",
    "2. Now open a normal terminal (not a julia session) and enter\n",
    "```bash\n",
    "localhost ~ » cd ~/.julia/dev/Hecke\n",
    "localhost dev/Hecke »\n",
    "```\n",
    "3. Now lets do a `git status` to see what git thinks:\n",
    "    ```\n",
    "    localhost dev/Hecke » git status \n",
    "    On branch master\n",
    "    Your branch is up to date with 'origin/master'.\n",
    "    ```\n",
    "    ```\n",
    "    Changes not staged for commit:\n",
    "      (use \"git add <file>...\" to update what will be committed)\n",
    "      (use \"git restore <file>...\" to discard changes in working directory)\n",
    "\t    modified:   src/GrpAb/Map.jl\n",
    "\n",
    "    Untracked files:\n",
    "\t    src/QuadForm/Torsion.jl\n",
    "    ```\n",
    "   This tells us that we made a bunch of changes to some files that were already there and we also added a new file that was not in the repository before."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "4. We now tell git about our fork of the Hecke repository. First we check which remote repositories it already knows about:\n",
    "    ```bash\n",
    "    localhost dev/Hecke » git remote -v\n",
    "    origin\thttps://github.com/thofma/Hecke.jl.git (fetch)\n",
    "    origin\thttps://github.com/thofma/Hecke.jl.git (push)\n",
    "    ```\n",
    "    This is the original repository, where the source code of Hecke resides. Since we don't have write access to directly write our changes to our repository, we will first push them to our remote repository that we forked before. To this end, we add this remote repository by doing\n",
    "    ```bash\n",
    "    git remote add $user https://github.com/$user/Hecke.jl.git\n",
    "    ```\n",
    "    where `$user` is our GitHub account name. (The first occurence could actually be anything, it is just a local name for this remote repository.). We can check the sucess of this operation by running `git remote -v` again."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "5. We create a branch by doing\n",
    "    ```bash\n",
    "    localhost dev/Hecke » git checkout -b cool_feature\n",
    "    Switched to a new branch 'cool_feature'\n",
    "    ```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "6. We now have to tell which changes we want to push. We do so\n",
    "    by using `git add` to tell it about the files we want to add.\n",
    "    ```bash\n",
    "    localhost dev/Hecke » git add src/GrpAb/Map.jl src/QuadForm/Torsion.jl\n",
    "    localhost dev/Hecke » git status                                                                               \n",
    "    \n",
    "    On branch cool_feature\n",
    "    Changes to be committed:\n",
    "      (use \"git restore --staged <file>...\" to unstage)\n",
    "        new file:   src/QuadForm/Torsion.jl\n",
    "        modified:   src/GrpAb/Map.jl\n",
    "    ```\n",
    "7. Commit the changes using `git commit` as follows:\n",
    "    ```bash\n",
    "    locahost dev/Hecke » git commit -m \"Cool new feature\"\n",
    "    [cool_feature f8b48437] Cool new feature\n",
    "    2 files changed, 1 insertion(+)\n",
    "    create mode 100644 Torsion.jl\n",
    "    ```\n",
    "    Here, \"Cool new feature\" is the message which should summarise the changes we made.\n",
    "    (Note that this message will appear in logs of the official repository once your changes are merged.)\n",
    "    \n",
    "    Alternatively we can use `git commit` (without `-m`), which we will drop us into an editor like\n",
    "    vim or emacs (depending on your local configurations), where we can enter our message."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "8. Push the branch your repository using `git push`:\n",
    "    ```bash\n",
    "    localhost dev/Hecke » git push user cool_feature\n",
    "    Username for 'https://github.com': user (your GitHub user name)\n",
    "    Password for 'https://user@github.com': (your GitHub password)\n",
    "    Enumerating objects: 24, done.\n",
    "    Counting objects: 100% (24/24), done.\n",
    "    Delta compression using up to 4 threads\n",
    "    Compressing objects: 100% (11/11), done.\n",
    "    Writing objects: 100% (15/15), 1.78 KiB | 1.78 MiB/s, done.\n",
    "    Total 15 (delta 12), reused 4 (delta 4)\n",
    "    remote: Resolving deltas: 100% (12/12), completed with 9 local objects.\n",
    "    remote: \n",
    "    remote: Create a pull request for 'cool_feature' on GitHub by visiting:\n",
    "    remote:      https://github.com/user/Hecke.jl/pull/new/cool_feature\n",
    "    remote: \n",
    "    To https://github.com/user/Hecke.jl.git\n",
    "     * [new branch]          cool_feature -> cool_feature\n",
    "```\n",
    "9. We now navigate to https://github.com/user/Hecke.jl, where a button for creating the pull request should pop up. Alternatively, we can use the link https://github.com/user/Hecke.jl/pull/new/cool_feature. At this point we can review our changes again and we could add more comments if we want. Once finished with this we just have to hit the green `Create pull request` button."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to add changes to your pull request\n",
    "\n",
    "This is very simple. We just make the changes locally and then do `git add`, `git commit` and `git push` as in steps 6-8 before."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to make a new pull request\n",
    "\n",
    "Let's assume that our pull request was sucessfully merged. In the meantime we have thought of another feature that we would like to add or a bug that we would like to squash. To do so, we need to create a new pull request. As suual, we navigate first to `~/.julia/dev/Hecke` as in step 2 before. Then\n",
    "\n",
    "1. Check out the master branch by doing `git checkout master`.\n",
    "2. Pull in the latest changes from the official repository by doing `git pull`.\n",
    "\n",
    "At this point, we can repeat steps 5-9 as above.\n",
    "\n",
    "**Important**: If we want to use the same name for the branch as before (in our case this was `cool_feature`), we first have to delete it invoking `git branch -d cool_feature`. Then we can continue with step 5.)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Julia 1.5.1",
   "language": "julia",
   "name": "julia-1.5"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.5.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}