Copier Workflow

This repository uses copier to create and maintain the core files. This is done to keep the settings consistent across all Buffalo Herd projects.

Overview

The premise behind copier is that there is a source repository that contains all of the core files that a project will need. This repository is used as the source, and copier makes a copy of that repository after getting configuration information from you about the specifics of the project that is being created. When finished the project will be created and will be ready to initialize and start developing.

Project Creation

To create a new project follow these steps:

  1. Make sure you have the following installed:

    • A python interpreter

    • pipx

    • uv

  2. From the command line, go to the directory where you want the project created.

  3. Run the following command (replace MyNewProject with the name of directory you want to put the project) to:

pipx run copier copy --vcs-ref main \
    https://codeberg.org/BuffaloHerd/BuffaloBlueprint.git \
    ./MyNewProject

  1. Change into that newly created directory and initialize uv with the following commands:

cd MyNewProject; uv sync

Once the project is created and initialized, you’ll notice two files that you’ll want to keep in your git repository:

  • .copier-answers.yaml: Stores the answers to all of the questions that were asked during the copying process.

  • uv.lock: Track the specific project dependencies.

Notes on Entering Content into Copier

  • The interface for copier tries to create reasonable default values for items to make the project creation process a bit easier.

  • Dr. Marshall is set up as an author to the project, so additional authors can be added through the multi-line entry in yaml syntax.

    • For example, suppose there are two co-authors that need to be added, Grace Hopper and Ada Lovelace. While Grace Hopper has an orcid, Ada Lovelace does not. Here is the yaml formatted information:

- name: Ada Lovelace
  email: ada@example.com
  given: Ada
  family: Lovelace
- name: Grace Hopper
  email: grace@example.com
  given: Grace
  family: Hopper
  orcid: https://orcid.org/0009-0007-6015-7076

  • Note that the orcid field for Ada Lovelace is omitted.

  • Once you are done entering text into the multi-line press the esc key followed by enter.

Answer Files

While uncommon, it can be useful to have the answers in a file and pass those answers into copier. One case might be to rerun copier using the answers from the prior run to create a second project. For example, to use the answers from the creation of MyNewProject to create a second project located in AnotherNewProject the command is:

pipx run copier copy --data-file MyNewProject/.copier-answers.yaml \
   --vcs-ref main https://codeberg.org/BuffaloHerd/BuffaloBlueprint.git \
   ./AnotherNewProject

Project Variables

The answers stored in the answer file are used to create project specific information. The mapping of the project variables to the files that use these variable is located in the copier project variables file.

Buffalo Blueprint Update

From time-to-time, there might be updates to the Buffalo Blueprint template project that will need to be applied to the target project. This can be done with an update step by running the following command from within the project directory:

pipx run copier update

Integration with Codeberg

With the project created locally, it needs to be associated with the corresponding repository on Codeberg that was set during the copier process. 1.Initialize git and set the remote

cd MyNewProject
git init
git branch -M main
git remote add origin https://codeberg.org/BuffaloHerd/MyNewProject.git

  1. Commit the generated files

git add -A
git commit -m "Initial commit from Buffalo Blueprint template"

  1. Push to Codeberg

git push -u origin main