gh-template repo for research projects

[jessb0t]

DONE Defined:

• "template-project" repo is created on GH
• pre-populated with all necessary scripts and readme

[jessb0t]

Pulled from wiki:

Project Template

Overview

The project template is a base project with all the basic functionality built in for developing Python or R projects. This helps save time and effort at the beginning of a project and keeps project development workflows and standards consistent across the lab. The base project uses Docker as a development platform and as a deployment platform.

By default the project contains a project directory, markdown templates for issues and pull requests, shell scripts to automate some basic actions, and yaml configurations for [GitHub Actions].

Usage

To use the template first clone the project template repository.

Once the repository has been cloned, open a terminal and cd into the directory.

Run the init.sh Bash script:

# "name" is the name of the project
# "name" should be all lower case, and contain no spaces
./init.sh name

To create the Docker container, run docker-compose up -d --build. This will run the Docker Compose configuration file and automatically build the Docker container and run it.

Note: The docker container will automatically mount the data and project_name directory. This will allow you to edit files under data and project_name as if you were editing them on your computer.

To access the container, run the command docker exec -it project_name_app_1 /bin/bash swapping project_name_app_1 for the name of the container.

Note: To figure out the name of the docker container you can use docker ps to list the containers that are currently running. Container names are usually the name the project directory followed by the service name, in this case app and then the instance number.

The container's working directory or the directory that the user is placed in by default is /workspace. In this directory, there is input and output, which are data file directories that can contain any data and are passed from the computer running Docker and the container. In this directory, there is also the project files, which include any Python or R script files.

In the container, cd to project_name and run either the RScript or Python script to execute the code.

Edit files

Any files under the data or project_name directories are accessible from either the container or the host. That means they can be edited in the host or container using tools that the user is most comfortable with.

On the host, navigate to the folder with the files and use a text editor or file viewer to interact with the files.

In the container the options are more limited, by default the container does not come with a text editor or file viewer just command line tools to manipulate the text file. It's not recommended to use this approach as user preferences are not saved across container reboots even though files under project_name and data persist across container reboots.

Issues and Pull Request Templates

These templates are simple forms to help users and contributors fill out Issues and Pull Request in a way that helps make them more readable.

Please reference the [wiki article]() that covers Issues workflow for more information.

[jessb0t]

Notes from 6/8 devOps meeting:

main: pre-reg, poster, publication dev: primary workspace dev-feature: branch off dev for major components

[jessb0t]

Workflow discussion from Slack 6/17:

In a nutshell: how do we only push part of dev to main?

I see us going about this in two ways:

1. we could selectively merge files/directories from dev into main with the git checkout dev fileFromDev command. Pros:
   • avoid merge conflicts
   • no need to refine protocol to merge in feature branches into dev Cons:
   • Could get quite tedious if we only needed to omit a small subset of files from dev
     2. Outline in CONTRIBUTING.md that anything that is not ready for publishing should likewise not be merged into dev. Could enforce through code reviews and branch protection rules. Pros:
   • PR from dev into main represents a concise release. Cons:
   • Feature branches that remain unmerged could get stale unless original author keeps track

---

Corollary question: we might want the readme files for dev and main to be distinct. How is this managed during that push to main process? Perhaps we could include README.md in the .gitignore of the main branch.

[jessb0t]

Released to team today!