Implementing version control
Once you start, you can’t stop tinkering. At some point, something is going to break. So as I intend to keep this code going for a while, I implemented version control with Git. This is a feature-rich version control system, and takes care of the steps in promoting the code you’re tinkering with to code that’s ready to publish. Finally, it also integrates nicely with the GitHub service on the web where you can share your code, and pushing to remote repositories such as on my Raspberry Pi. No more cutting and pasting and associated typos.
Once completed, the setup will look like this:
Atom [UI for] -> Git on Mac <-> GitHub [also for public sharing] -> Git on RPi
Spikes
Figuring this out took a lot of searching, as I didn’t find the documentation particularly enlightening. Here’s recommended reading.
Setting up Git, GitHub and Atom
Git was already installed in my Mac, and is part of Atom by default. So no need to install anything more. But there is a lot of other setting up to be done.
Before making the first Git push, I set up the files to ignore by adding the following items to my .gitignore file. These are: the environment files that are set up by the system; or data files that are created at run time; or personal information that I don’t want you to see! Note the **/ syntax which forces the file to be ignored from all subfolders.
__pycache__* : used by Python runtime
Icon*, **/*.DS_Store : hidden files used by macOS
.git : hidden files used by Git
*_old : a useful way of hiding files you might be tinkering way
credentials.py : secrets needed for the API
**/*_bar.svg, **/*_pie.svg : these graphs are made from the data at run time
database.sqlite3 : created by the main code on first connection and updated at run time
Next up is to create the target repository on GitHub. This is done by logging into the GitHub dashboard, and creating a new repository from there. Mine is called https://github.com/Schmoiger/pybloom and I encourage you to go have a look there.
Git (the local repository) needs to know this GitHub (remote repository) URL, so the next step is to add it to the Git config. This is done from Terminal, using the following command:
git remote add origin https://github.com/<your username>/<your app name>
This command associates the name origin to the remote repository URL, which makes management within Git and Atom a little easier. (If you’re so inclined, you could instead clone my repo instead, and work on my code. We’ll do this in the next section on setting up the Raspberry Pi) Now we’ve told Git where your remote repository is, we’ve got to tell who you are, so that Git can tell GitHub. In other words, we have to set up your email address in Git to be accepted by GitHub as an authenticated user.
git config --global user.email "email@example.com"
The email address is the one set up in GitHub. It doesn’t have to be a real address; GitHub will set up a “noreply” email for you if you wish.
We don’t configure the password in the same way. Instead, if you now boot Atom you should see a login window in the GitHub pane. This asks for the login token, which you’ll need to get from https://github.atom.io/login, then paste into Atom.
Setting up the Raspberry Pi
Git comes pre-installed in Raspberry Pi OS, so no further installation necessary. But as with the Mac, there is configuration to be done.
git config --global user.name "<your username>"
git config --global user.email "<your email>"
First step is to tell the git instance on the RPi who you are. By now everyone has hundreds of username/ email combinations. Rather than creating another one, I’m re-using my GitHub identity.
git clone https://github.com/Schmoiger/pybloom.git Projects
If you’re cloning my repo into your Projects folder, use the statement above, and a copy of the repo will be cloned into a pybloom subfolder. Otherwise change the url and the destination to suit your own environment.
The final step is to copy across the credentials.py file into the pybloom folder, as it has all your secrets for the API login.
Documentation
Arguably, the most important part of the repository is the documentation. I’ve created three:
README.md - bite-sized summary of the key things you need to know to use the program
Blog post - this set of posts (not in GitHub, but on https://blog.mindrocketnow.com)
PyBloom_manual.html - all the post put together into a single document, for convenience
Putting it together
.gitignore
__pycache__*
Icon*
.git
**/*.DS_Store
**/*_bar.svg
**/*_pie.svg
*_old
credentials.py
database.sqlite3
Workflow for making changes
Make changes in dev environment, using Atom
Commit in Git (after testing), then commit to GitHub, from within Atom
SSH into the RPi, type workon pybloom to work in the virtual environment
Pull the code changes by typing git pull
Re-start the web server by typing ctrl+C then flask run --host=0.0.0.0