The Ten Git-mmandments

Herein lies precious Git-related wisdom, do not disregard at your own convenience!

1. Do NOT treat Git repositories like Google Drive.
   • Git repositories do not exist for you to backup all your files (e.g., cache, output and log files).
   • Do not be trigger happy with ```git add --all```.
   • Do not add whole directories.
   • Maintain a minimalistic mentality, i.e., carefully consider what files are important with the focus on successfully allowing the user to run your code.
2. Do NOT include .pyc files, the entire __pycache__ folder and .DS_Store files.
   • Basically, you have been warned.
3. Do NOT ignore .gitignore.
   • They do not exist for no reason, create one to satisfy the above rules.
   • Visit https://git-scm.com/docs/gitignore for more information on formatting one.
   • Do not skip the following example:

   > Sometimes, you might want to code using an IDE on your personal computer, git push and then git pull onto a workstation to run the code.

   > As expected, you run into an error, nano into the file with the error and make the necessary changes.

   > The code now works and you happily git push from the workstation, with all your output and cached folders.

4. Do NOT send a merge request with over 453 changed files - this is impossible to review!
   • Do not operate with the mentality of only submitting completed working code.
   • Do not forget that little and often with code review is better than the former.
   • Besides the mundane rationale of catching your mistakes and getting feedback quicker rather than letting than accumulate, it allows the reviewer to better track and follow your changes.
5. Do NOT forget the concept and importance of source control.
   • This is a big one. Basically, when you are coding as a team, or if your work is derived from another user, or needs to be passed on to future users, you must consider code maintenance and management.
   • For example, as much as possible, do not explicitly include other people's code in your own repository, because when they update their code, you do not want to repeat the cloning or downloading process again, or have to sieve through all your and their code to find what has changed and needs to be updated. What you do want is to simply perform a ```git pull```. To that end, do not forget git submodules exist for a very good reason. See https://git-scm.com/book/en/v2/Git-Tools-Submodules.
   • Along those lines, you also do not want to edit someone else's code as much as possible.

   > For example, say you import the python package phreeqpy that serves as a wrapper for phreeqc, which is a piece of software written in C that you wish to use.

   > You quickly realise one of the files, ```phreeqpy_dll.py``` is causing errors, and needs to be modified to suit your needs.

   > You might wonder "Wouldn't the easiest solution be to make a new repository for phreeqpy, replace the _dll file with a newly edited (by you) _dll2 file and adding it as a submodule (*gasps* something about explicitly including someone else's code)? Clearly, the _dll2 file contains everything required to perform the job!"

   > However, what you do not realise is that making a new repository means having to deal with the compilation of phreeqc underneath it (which is the job of phreeqpy), which will result in more work further down the road because you have effectively, albeit inadvertently, involved yourself in managing phreeqpy, and all the hard work required to make it interface with phreeqc, which is not your job.

   > Indeed, do not rule out the possibility that it will probably be much less painful to make a single wrapper _dll2 file, and have your own module in your own repository import whatever is needed from the original unedited _dll file and extend its function by also importing your _dll2 file.

   > This segregation of your and their unedited code makes life way easier since you effectively only have to deal with your own code.

   • As a maxim, you do not ever want to add a file to a repository that you did not create.
6. Do NOT think once when having to modify someone else's code.
   • The previous rule does not consider the case when you have no choice but to modify someone else's code in order to make it work. This might happen when you are trying to integrate their software with other pieces of software, and a mere wrapper function will not suffice. By the way, side tracking a little, do not use the horrible shortcut of writing code to convert a .py file to .txt file, edit it like a text file before converting it back to a .py file and importing it. Do not forget wrapper functions exist for a reason. Moreover, when importing user-defined variables into your program, please do not format it as a text file and execute it like a .py file. It makes future integration and extension an absolute nightmare. Do not forget the literal eval function exists too.
   • Moving on, what you can do here is:

   > Create a new repository separate from your present repository.

   > Branch the (target) person's project into your new repository. The term for such a "cross-repository" branch is fork.

   > Inside your new repository, make a new branch where you make your modifications to their code as git commits with a merge request back into the ```main``` (of your new repository) at the end.

   > If you are in the mood, you can even make a ```pull request``` back to the (target) person's project branch with your new code.

   > But considering your own needs first, you can then add this new branch as a submodule in your present repository.

   > Again, do not forget that untangling other people's code is a horrible process, so you want to keep yours and their code as separate as possible.

7. Do NOT include autogenerated files in your git repository.
   • Do not forget that autogenerated files, e.g., .o and .d files, will change when you recompile them even if their source files have not.
   • Instead, add the compilation instructions to your README and leave that to the user. Again, do not forget ```make``` files exist.
8. Do NOT forget to test your code on a workstation.
   • It is not a matter of making sure your code runs on a specific workstation, but to remember that the end user will have a different machine with a different setup.
   • For example, your code may require a compiler GLIBC >= 2.29 that in turn requires Ubuntu >=20.04. A quick check will reveal, as of August 2022, that most machines are running an older version.
   • Therefore, do not forget to include a detailed list of instructions and system requirements when asking someone else to review your code.
   • You do not want your reviewer (and therefore you) to spend ages just to debug software requirement related errors.
   • As such, do not miss an opportunity to test your code on a 'fresh' machine. It may be helpful to even record the system specifications when your code runs successfully to aid with that.
9. Do NOT be afraid to clarify git related concepts as early as possible.
   • Especially when it is your first time using Git.
10. Do NOT forget to share your mistakes and helpful pointers with your colleagues.
    • We certainly do not wish to entertain the situation of multiple people making the same mistakes with the same reviewer.

"Do not" counter: 37