Rocks template repo

This repository template provides a basic setup to help you get started quickly with developing your own rock.

Table of Contents

• Setup Instructions
• Directory Structure
• Building the Rock

Setup Instructions

1. Start a new repository from this template

Check GitHub's documentation on creating a repository from a template

1.1. Create secrets, if needed

Important

If your repository is internal or private, you need to create the following secrets in your repository:

• REPO_CLONER_TOKEN: use a fine grained token with read:content and read:metadata permissions. Make sure the token's "resource owner" is canonical, and has access to the right repositories (not just public in this case). Also, please note that fine-grained tokens have an expiration date. So if and when experiencing CI problems checking out the repository, make sure the token is still valid.

2. Customize the Template

This template comes with a basic setup to get you started. Here's what you need to customize:

• rockcraft.yaml: This is your rock's recipe! Adjust its contents, as well as its parent directories' names according to your rock's name and version.
• task.yaml: This is your tests' file, it contains the required instructions written in bash for your rock to be tested using spread.
• SECURITY.md.template: Edit the template with your repo's details and set the security policy by renaming this file to SECURITY.md.
• CODEOWNERS: Optional, but recommended. Read more about CODEOWNERS.

Directory Structure

Here's an overview of the directory structure of the repository:

my-rock-name/                 # Directory containing all versions of a single rock
   └─ 0.1/                    # Directory containing the rock project file for a specific version
      └─ rockcraft.yaml       # Rock project file
      └─ spread.yaml          # Spread test configuration
      └─ spread/              # Spread tests directory
         └─ .extension        # Functions used internally by spread tests
         └─ general/test/     # Directory containing tests
            └─ task.yaml      # Test file
.gitignore
CODEOWNERS                    
README.md                     # Top level document containing this specification
SECURITY.md.template          # Security policy template

Building, testing and uploading the Rock

To build, test and upload the rock to GHCR, simply commit your rockcraft.yaml file and check the GitHub actions.

Note

Before committing your rockcraft.yaml, it is recommended that you pack it with Rockcraft run a smoke test locally. Check the Rockcraft documentation to learn more.

Sync with template

A Makefile is provided to sync the repository with the latest template changes. To do so, simply run:

make sync-with-template