Merge pull request #94 from MolSSI-Education/2022-review

2022 review

Author: janash

_episodes/01-package-setup.md

@@ -169,7 +169,6 @@ You should see the following directory structure.
 ├── README.md                       <- Description of project which GitHub will render
 ├── molecool                        <- Basic Python Package import file
 │   ├── __init__.py                 <- Basic Python Package import file
-│   ├── _version.py                 <- Automatic version control with Versioneer
 │   ├── functions.py                <- Starting package module
 │   ├── data                        <- Sample additional data (non-code) which can be packaged. Just an example, delete in production
 │   │   ├── README.md
@@ -198,10 +197,10 @@ You should see the following directory structure.
 │   ├── index.rst
 │   ├── make.bat
 │   └── requirements.yaml           <- Documenation building specific requirements. Usually a smaller set than the main program
+├── pyproject.toml                  <- Generic Python build system configuration (PEP-517).
 ├── readthedocs.yml
 ├── setup.cfg                       <- Near-master config file to make house INI-like settings for Coverage, Flake8, YAPF, etc.
 ├── setup.py                        <- Your package's setup file for installing with additional options that can be set
-├── versioneer.py                   <- Automatic version control with Versioneer
 ├── .codecov.yml                    <- Codecov config to help reduce its verbosity to more reasonable levels
 ├── .github                         <- GitHub hooks for user contribution, pull request guides and GitHub Actions CI
 │   ├── CONTRIBUTING.md
@@ -235,7 +234,6 @@ We will first be working in the `molecool` folder to build our package, and addi
 │   ├── tests                       <- Unit test directory with sample tests
 │   │   ├── __init__.py
 │   │   └── test_functions.py
-│   └── _version.py                 <- Automatic version control with Versioneer
 ~~~
 {: .output}
 
@@ -280,12 +278,7 @@ Contents of `molecool/molecool/__init__.py`:
 # Add imports here
 from .functions import *
 
-# Handle versioneer
-from ._version import get_versions
-versions = get_versions()
-__version__ = versions['version']
-__git_revision__ = versions['full-revisionid']
-del get_versions, versions
+from ._version import __version__
 ~~~
 {: .language-python}
 
@@ -323,28 +316,41 @@ which describes the function.
 
 We will be moving all of the functions we defined in the Jupyter notebook into python modules (`.py` files) like these.
 
+> ### Before proceeding, make sure your `pip` and `setuptools` packages are up-to-date.
+> 
+> ~~~
+> conda update pip setuptools
+> ~~~
+> {: .language-bash}
+> or
+> ~~~
+> pip install --upgrade pip setuptools
+> ~~~
+> {: .language-bash}
+{: .callout}
+
 ### Installing from local source.
 
 You may be accustomed to `pip` automatically retrieving packages from the internet.
-You can also install packages from local sources that contain a `setup.py` file.
 
 To develop this package, we will want to use what is called "development mode", or an "editable install",
 so that we can try out our functions and package as we develop it.
-We access development mode using the `develop` command to `setup.py`, or the `-e` option to `pip`.
+We access development mode using the `-e` option to `pip`.
 
-#### Reviewing `setup.py`
+#### Reviewing the generated config files
 Return to the top directory (`molecool`).
-One of the files CookieCutter generated is a `setup.py` file.
-`setup.py` is the build script for [setuptools].
-It tells setuptools about your package (such as the name and version) as well as which code files to include.
+Two of the files CookieCutter generated are `pyproject.toml` and `setup.cfg`.
+These are the configuration files for our packaging and testing tools.
+`pyproject.toml` tells [setuptools] about your package (such as the name and version) as well as which code files to include.
 We'll be using this file in the next section.
 
 #### Installing your package
 A development install will allow you to import your package and use it from anywhere on your computer.
 You will then be able to import your package into scripts in the same way you import `matplotlib` or `numpy`. 
 
-A development installation uses the `setup.py` file to install your package
-by inserting a link to your new project into your Python site-packages folder.
+A development installation inserts a link to your project into your Python
+`site-packages` folder so that updates are immediately available the next time
+you launch Python, without having to reinstall your package.
 To find the location of your site-packages folder, you can check your Python path.
 Open Python (type `python` into your terminal window), and type
 

_episodes/02-git.md

@@ -53,7 +53,7 @@ You should have `git` installed and configured from the setup instructions.
 
 In this section, we are going to  edit files in the Python package that we created earlier, and use `git` to track those changes.
 
-First, use a terminal to `cd` into the top directory of the local repository.
+First, use a terminal to `cd` into the top directory of the local repository (the outer molecool directory).
 
 In order for `git` to keep track of your project, or any changes in your project,
 you must first tell it that you want it to do this.
@@ -329,7 +329,7 @@ We are asking git to show us the difference between the current files and the se
 Lines that have been added are indicated in green with a plus sign next to them (`+`),
 while lines that have been deleted are indicated in red with a minus sign next to them (`-`)
 
-## Viewing our previous versions
+## Viewing previous versions
 
 If you need to check out a previous version,
 
@@ -390,6 +390,90 @@ $ git commit -m "Initial commit after CMS Cookiecutter creation, version 1.0"
 > {: .solution}
 {: .challenge}
 
+## Exploring git history
+
+When working on a project, it is easy to forget exactly what changes we have made to a file.
+To check this, do
+
+~~~
+$ git diff HEAD README.md
+~~~
+{: .language-bash}
+
+We should get a blank result.
+"HEAD" is referencing the most recent commit.
+Since we committed our changes `to README.md`, there is no difference to show.
+
+Open your `README.md` and add the following line to the end of it.
+
+~~~
+This line doesn't add any value.
+~~~
+Save that file and run the same command.
+~~~
+$ git diff HEAD README.md
+~~~
+{: .language-bash}
+
+~~~
+diff --git a/README.md b/README.md
+index 94e0b50..a68f349 100644
+--- a/README.md
++++ b/README.md
+@@ -17,6 +17,8 @@ This package requires the following:
+   - numpy
+   - matplotlib
+
++This line doesn't add any value.
++
+ ### Copyright
+~~~
+{: .output}
+
+To compare against the commit just before the most recent commit, add "~1" to end of "HEAD":
+
+~~~
+$ git diff HEAD~1 README.md
+~~~
+{: .language-bash}
+
+~~~
+diff --git a/README.md b/README.md
+index e778cd4..94e0b50 100644
+--- a/README.md
++++ b/README.md
+@@ -13,6 +13,10 @@ This repository is currently under development. To do a development install, dow
+
+ in the repository directory.
+
++This package requires the following:
++  - numpy
++  - matplotlib
++
+ ### Copyright
+~~~
+{: .output}
+
+
+If we want to compare against a specific commit, we can first do `git log` to find the commit's ID, and then do:
+
+~~~
+$ git diff *commit_id* README.md
+~~~
+{: .language-bash}
+
+Another problem that we sometimes encounter is wanting to undo all of our changes to a particular file.
+This can be done with
+
+~~~
+$ git checkout HEAD README.md
+~~~
+{: .language-bash}
+
+If you open `README.md` you will see that it has reverted to the content from the most recent commit.
+
+Of course, you could also replace `HEAD` here with `HEAD~1` or a specific commit ID.
+
 
 ## Creating new features - using branches
 
@@ -420,7 +504,25 @@ $ git checkout -b zen
 ~~~
 {: .language-bash}
 
-Next, add a new function to your `functions.py` module.
+We can visualize what branching looks like with some simple figures.
+Before branching, imagine a git commit history that looks like this.
+In the diagram below, each circle represents a git commit.
+There have been two commits, and the HEAD is currently after commit 2.
+
+<center><img src='../fig/github_workflows/git_history_0.svg'></center>
+
+After we have created a new branch and checked it out, we can imagine our git history looking like this.
+The `zen` branch 'branches' or starts from the point where we used the git branch command. 
+
+<center><img src = '../fig/github_workflows/git_branch.svg'></center>
+
+Now, when we make a commit on the `zen` branch, our changes will continue from this point, leaving the main branch unchanged.
+Note that we have not yet made a commit, but this diagram is for illustrative purposes.
+
+<center><img src = "../fig/github_workflows/branch_development.svg"></center>
+
+Now that we have a better understanding of what branching looks like, lets make some changes to the `zen` branch.
+Add a new function to your `functions.py` module.
 We are going to add the ability to print "The Zen of Python". You can get the Zen of Python by typing
 
 ~~~
@@ -821,6 +923,153 @@ $ git branch -d zen
 > {: .solution}
  {: .challenge}
 
+## Ignoring files - .gitignore
+
+Sometimes while you work on a project, you may end up creating some temporary files.
+For example, if your text editor is Emacs, you may end up with lots of files called `<filename>~`.
+By default, Git tracks all files, including these.
+This tends to be annoying, since it means that any time you do `git status`,
+all of these unimportant files show up.
+
+We are now going to find out how to tell Git to ignore these files,
+so that it doesn't keep telling us about them ever time we do `git status`.
+Even if you aren't working with Emacs, someone else working on your project might,
+so let's do the courtesy of telling Git not to track these temporary files.
+First, lets ensure that we have a few dummy files.
+Make empty files called `testing.txt~` and `README.md~` in your repository using your text editor of choice.
+
+
+While we're at it, also make some other files that aren't important to the project.
+Make a file called `calculation.out` in `molecool/data` using your text editor of choice.
+
+Now check what Git says about these files:
+
+~~~
+$ git status
+~~~
+{: .language-bash}
+
+~~~
+On branch main
+Your branch is up to date with 'origin/main'.
+
+Untracked files:
+  (use "git add <file>..." to include in what will be committed)
+
+	README.md~
+	molecool/data/calculation.in
+	molecool/data/calculation.out
+	testing.txt~
+
+nothing added to commit but untracked files present (use "git add" to track)
+~~~
+{: .output}
+
+Now we will make Git stop telling us about these files.
+
+Earlier, when we looked at the hidden files, you may have noticed a file called `.gitignore`.
+Cookiecutter created this for us, however, GitHub also has built in `.gitignore` files you can add when creating an empty repository.
+
+This file is to tell `git` which types of files we would like to ignore (thus the name `.gitignore`)
+
+Look at the contents of `.gitignore`
+
+~~~
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+...
+~~~
+
+Git looks at `.gitignore` and ignores any files or directories that match one of the lines.
+Add the following to the end of `.gitignore`:
+
+~~~
+# emacs
+*~
+
+# temporary data files
+*.in
+*.out
+
+~~~
+
+Now do "git status" again. Notice that the files we added are no longer recognized by git.
+
+~~~
+$ git status
+~~~
+{: .language-bash}
+
+~~~
+On branch main
+Your branch is up to date with 'origin/main'.
+
+Changes not staged for commit:
+  (use "git add <file>..." to update what will be committed)
+  (use "git checkout -- <file>..." to discard changes in working directory)
+
+	modified:   .gitignore
+
+no changes added to commit (use "git add" and/or "git commit -a")
+~~~
+{: .output}
+
+We want these additions to `.gitignore` to become a permanent part of the repository:
+
+~~~
+$ git add .gitignore
+$ git commit -m "Ignores Emacs temporary files and data directory"
+~~~
+{: .language-bash}
+
+One nice feature of `.gitignore` is that prevents us from accidentally adding
+a file that shouldn't be part of the repository.
+For example:
+
+~~~
+$ git add data/calculation.in
+~~~
+{: .language-bash}
+
+~~~
+The following paths are ignored by one of your .gitignore files:
+data/calculation.in
+Use -f if you really want to add them.
+~~~
+{: .output}
+
+It is possible to override this with the `-f` option for `git add`.
 
 ## More Tutorials
 If you want more `git`, see the following tutorials.