Repository Usage

To build our repository template as-is from start to finish, the following procedure should be implemented:

1. From the root of the repository, run the following bash command in a terminal:

   python run_all.py
   

If you are using Windows, you will need to run all bash commands in administrator mode. This is because creating a symbolic link in Windows requires administrator privileges.

It is also possible to run only specific modules. For example, to build the repository template running each module individually, the following procedure can be implemented instead:

1. From the data subdirectory, run the following bash command in a terminal:

   python make.py
   

2. From the analysis subdirectory, run the following bash command in a terminal:

   python make.py
   

3. From the paper_slides subdirectory, run the following bash command in a terminal:

   python make.py
   

In certain situations, it may be practical to only run certain modules. For example, a user may wish to make language changes to the paper for a project and only rerun paper_slides. In such cases, it is critical that users run not just the target module, but all downstream modules that rely on the target module.

To reiterate golden rule #2: important commits must follow a complete run of the relevant build scripts. To absolutely guarantee replicability, build the complete repository from start to finish.

Python Environment

Shell vs. IDE

The instructions for setting up command line usage and building the repository assume you are running Python via shell as opposed to an integrated development environment (IDE) such as Spyder.

If you are using an IDE, it is critical to note that environment variables such as PATH for your IDE may be different from those in your system environment. Therefore, you will need to tailor the setup instructions to be specific for your IDE.

Administrator mode

If you are using Windows, you must run the GSLab Make library on administrator mode. To do so, open your terminal/IDE by right clicking and selecting Run as administrator.

To permanently set up your terminal/IDE to run as administrator mode:

1. Right click on the shortcut for your terminal/IDE and select Properties.
2. Click Advanced and check Run as administrator.
3. Click OK.

---

Commits should normally involve changes to code in only one module.

Any commit that involves changes to code should happen immediately after running a directory's build script (make.py). If you do not wish to run all components of a directory you can comment out those components in make.py before running it. Exceptions to this rule can be made for minor edits that do not affect the substance of the code (e.g., editing a comment) or in cases where you wish to commit work in progress that is not ready to run; in these cases, your commit message should indicate that the build script was not run (e.g., "make.py not run on this commit").

Commits of these types must follow complete runs of make.py with nothing commented out: (i) anything merged to master; (ii) any commit that defines a final issue deliverable; (iii) the final commit before a pull request.