Guide

So you want to create a library for the Savi language, and you want the GitHub repository for it to always have the latest CI automation affordances that the standard library repositories have?

You've come to the right place!

Overview

This wiki page will walk you through the steps of creating a new GitHub repository that uses this repository as an git upstream, allowing any changes to the CI automation held in this repository to trigger an automatic pull request into your own repository that you can approve and merge at your leisure.

Note that you're free to make changes to the files in your own repository, and any conflicts in the incoming changes will need to be settled by git automatically or by you manually in the usual way. Some changes are expected/required (like setting up your own README.md and LICENSE.md), but overall this repository is structured in such a way as to keep the need for manual intervention to a minimum, so as to avoid merge conflicts in the normal case.

Part of that is the reason why you're reading this guide in a GitHub Wiki page rather than in the README.md in the repo - so that this guide can be updated over time without causing continuous merge conflicts with the differing README.md text in all of the downstream repos.

Repository Creation

To create a new repository using this repository as its base:

• click the "+" icon in the upper-right corner of the GitHub UI
• in the drop-down menu, select "Import Repository"
• in the "old repository" text field, paste https://github.com/savi-lang/base-standard-library
• configure the name, owner, and public/private setting as desired in the "new repository details" section

Note that you likely do NOT want to use the GitHub "Fork" button to "fork" this repository, because forked repositories are crippled in GitHub, being considered to be largely identical to their upstream rather than being treated as independent projects that share a bit of common git history with their upstream, as is the case with the intended usage of this repository.

Note also that this setup process does NOT use a GitHub "template repository", because that mechanism is intended for a one-time copy of files, rather than an ongoing upstream relationship that can pull in new changes over time.

Repository Description, Topics, and Settings

Once you have imported the base repository, you'll likely want to add some metadata in GitHub that can help users find and understand your library.

• Click the "gear" icon next to the "About" section on the right side of the GitHub repository view.
• Add a short "Description" that describes what your library does.
• In the "Topics" list, add the topics savi and library and any others that are appropriate (based on what your library does, what protocol it implements, etc).
  • The two topics savi and library will help Savi users more easily find your library, both in the GitHub UI, and in Savi-specific library discovery tools.
• In the "Include in home page" section, you'll likely want to disable Packages and Environments, leaving only Releases (which will correspond to library package versions).

You'll also need to explicitly enable GitHub Actions (they seem to be off by default for imported repositories).

• Click the "Settings" tab of the main repository view.
• Click "Actions" then "General" in the left sidebar of the Settings view.
• In the "Actions permissions" section, click "Allow all actions".
• Then click "Save" to finalize the "Actions permissions" settings section.

File Changes

The next step is to clone your new repository locally, so you can make a few file changes in git and commit them.

Alternatively, it is also possible to make these changes in the editor of the GitHub UI.

Change LICENSE.md

The initial LICENSE.md is a standard BSD 3-Clause license that marks Joe Eli McIlvain as the copyright holder, since he is the creator and maintainer of most of the standard library repositories, which all use this repository as a base.

You'll want to mark yourself as the copyright holder, and possibly switch to a different license text if you like.

Change README.md

The initial README.md is a short description of this repository and a link to this guide.

You'll want to change it to reflect the name and description of your own project.

Secrets Setup

In order for the common CI workflows to work properly, you'll need to set up a variety of secrets that they can use.

If your repository is in an organization, you can share the same secrets across many repositories without setting them up each time by setting them up as Organization Secrets. Otherwise, you'll need to set them up as Repository Secrets. There currently is no feature for setting up User Secrets akin to Organization Secrets, which is one reason you may want to consider creating an Organization like this one to host your libraries if you want to manage many of them.

Create BOT_GITHUB_TOKEN

Create a Personal Access Token that includes at least the following scopes/permissions:

• repo
• workflow

Unfortunately, the GITHUB_TOKEN that comes automatically equipped inside GitHub Actions workflows does not have some of the scopes we need (e.g. the workflow scope), so we need to create a personal token and save it as a distinct secret named BOT_GITHUB_TOKEN.

If your repository/organization is maintained by multiple contributors rather than just yourself, you should strongly consider creating a bot user account like this one instead of using a personal access token tied to your single user. Unfortunately, there is no Organization-level equivalent of a Personal Access Token.

Create BOT_ZULIP_API_KEY and BOT_ZULIP_EMAIL

Create a Bot in your Personal Settings in Zulip of type "Generic bot". Assign it a "Full name" like alice-bot and "Bot email" like alice-bot@savi.zulipchat.com (note that you are creating a new email address for the bot, not referring to an email address that is expected to already exist).

After the bot is created, note its "API KEY" and "BOT EMAIL" in the "Active Bots" view.

Save them as secrets named BOT_ZULIP_API_KEY and BOT_ZULIP_EMAIL, respectively.