https://github.com/repronim/reproschema-protocol-cookiecutter
A cookiecutter for reproschema protocols.
https://github.com/repronim/reproschema-protocol-cookiecutter
Last synced: about 1 year ago
JSON representation
A cookiecutter for reproschema protocols.
- Host: GitHub
- URL: https://github.com/repronim/reproschema-protocol-cookiecutter
- Owner: ReproNim
- Created: 2023-12-18T21:51:32.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-01T02:55:24.000Z (almost 2 years ago)
- Last Synced: 2025-04-09T21:48:43.845Z (about 1 year ago)
- Language: Python
- Size: 103 KB
- Stars: 0
- Watchers: 10
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# reproschema-protocol-cookiecutter
A [Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) for [ReproSchema](https://github.com/ReproNim/reproschema) protocols.
You can find a demo protocol [here](https://github.com/ReproNim/reproschema-demo-protocol) generated by this cookiecutter. Here is our [online document](https://www.repronim.org/reproschema/) to help you customize your newly generated protocol based on specific research needs. The relevant chapters are as follows:
- [Creating a Research Protocol Using Cookiecutter](https://www.repronim.org/reproschema/41_create_new_protocol/)
- [Adopting Assessments from the reproschema-library](https://www.repronim.org/reproschema/42_adopt_assessments/)
- [Creating New Assessments for Unique Research Needs](https://www.repronim.org/reproschema/43_create_new_assess/)
- [Add a Feedback Section](https://www.repronim.org/reproschema/44_setup_feedback/)
- [Finalizing the Protocol](https://www.repronim.org/reproschema/45_finalize_protocol/)
- [Toolkit](https://www.repronim.org/reproschema/46_tools/)
## Prerequisites
The following are required and recommended tools for using this cookiecutter and the ReproSchema protocol it generates. This is all a one-time setup, so if you have already done it, skip to the [next section](#creating-a-new-project)!
* **pipx**
pipx is a tool for managing isolated Python-based applications. It is the recommended way to install Poetry and cruft. To install `pipx` follow the instructions here: https://pypa.github.io/pipx/installation/
* **cruft**
cruft is a tool for generating projects based on a cookiecutter (like this one!) and keeping those projects updated if the original cookiecutter changes. Install it with `pipx` by running:
```shell
pipx install cruft
```
You may also choose to not have a persistent installation of cruft, in which case you would replace any calls to the `cruft` command below with `pipx run cruft`.
## Creating a new protocol
### Step 1: Generate the protocol files
To generate a new Reproschema protocol, run the following:
```bash
cruft create https://github.com/ReproNim/reproschema-protocol-cookiecutter
```
You will be prompted for a few values. The defaults are fine for most
protocols, but do name your protocol something that makes sense to you!
The interactive session will guide you through the process:
1. `protocol_name`: Name of the protocol; use kebab-case with no spaces.
Suggestions:
- `reproschema-protocol`
- `mood-protocol`
- `media-selection`
- `mental-health-survey`
2. `github_org`: Your GitHub username or organization name. This is used to construct links to documentation pages.
3. `protocol_description`: Description of the protocol.
- A single brief sentence is recommended
- Can easily be modified later
4. `number_of_activities`: How many activities/assessments do you want to create? Choose between 1 and 5; later, it will randomly generate the number of activities you choose for your protocol.
5. `full_name`: Your name
6. `email`: Your email
7. `license`: Choose a license for the project. If your desired license is not listed, you can update or remove the `LICENSE` file in the generated project.
Then, go to your protocol folder
```bash
cd my-reproschema-protocol # using the folder example above
make setup
```
### Step 2: Create a GitHub repository
1. Go to https://github.com/new and follow the instructions, being sure NOT to add a `README` or `.gitignore` file (this cookiecutter template will take care of those files for you). Be sure your GitHub repo uses the same `protocol_name`
2. Add the remote to your local git repository
```bash
git remote add origin https://github.com/{github-user-or-organization}/{protocol_name}.git
git branch -M main
git push -u origin main
```
3. Create the gh-pages branch
- Fetch the latest changes from your repository (if any):
```bash
git fetch origin
```
- Create and switch to the new gh-pages branch:
```bash
git checkout -b gh-pages
```
- Push the gh-pages branch to remote:
```bash
git push --set-upstream origin gh-pages
```
This branch allows you to deploy your ReproSchema UI publicly.
## Keeping your project up to date
To be up-to-date with the template, first check if there is a mismatch
between the project's boilerplate code and the template by running:
```bash
cruft check
```
This indicates if there is a difference between the current project's
boilerplate code and the latest version of the project template. If the project
is up-to-date with the template:
```output
SUCCESS: Good work! Protocol's cruft is up to date and as clean as possible :).
```
Otherwise, it will indicate that the project's boilerplate code is not
up-to-date by the following:
```output
FAILURE: Protocol's cruft is out of date! Run `cruft update` to clean this mess up.
```
## Credits
This cookiecutter was made with pieces from
[Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) and [linkml-project-cookiecutter](https://github.com/linkml/linkml-project-cookiecutter).