Set up a new control-toolbox application or package

[ocots]

Set up a new control-toolbox application or package

This guide explains the process for setting up a new repository using this template, thanks to a new automated workflow.

Step 1: Create the Repository

• Click on the button below to create a new repository from this template:

  

• Choose a name for your repository (e.g., MyApp.jl) and an owner.

Warning

The repository name must end with the .jl suffix.

Step 2: Add Keys and Secrets

For documentation and code coverage to work, you need to add two secrets to your new repository (Settings > Secrets and variables > Actions):

1. DOCUMENTER_KEY: A secret to allow documentation deployment.

   • Generate it by running the following Julia code and following the instructions:

     using DocumenterTools
     DocumenterTools.genkeys(user="my-owner", repo="MyApp.jl") # Replace with your owner/repo

   • When adding the deploy key to your repository, ensure you grant it write access.

2. CODECOV_TOKEN (Optional): A secret for uploading coverage reports to Codecov.

   • If you choose not to use Codecov, you should:
     1. Delete the file .github/workflows/Coverage.yml.
     2. In README.template.md, remove the word Coverage from the line that looks like <!-- INCLUDE_BADGES: ..., Coverage, ... -->.

Step 3: Configure Repository Settings

Before running the automated setup workflow, configure the necessary permissions and GitHub Pages settings:

1. Permissions: Go to Settings > Actions > General, select Read and write permissions, and check Allow GitHub Actions to create and approve pull requests.
2. GitHub Pages: Go to Settings > Pages, select the gh-pages branch as the source, and save. This will publish your documentation.

Step 4: Run the Automated Setup Workflow

1. Go to the Actions tab of your new repository.
2. In the left sidebar, click on the "Setup Repository" workflow.
3. Click the "Run workflow" button on the right, and then confirm by clicking the green "Run workflow" button again.

This workflow will create a Pull Request that automatically:

• Replaces all instances of CTAppTemplate and control-toolbox/CTAppTemplate.jl.
• Renames src/CTAppTemplate.jl to src/YourAppName.jl.
• Generates a new uuid and sets the authors field in Project.toml.
• Updates the default assignee to be you in issue templates (.github/ISSUE_TEMPLATE) and in the auto-assign workflow (.github/workflows/AutoAssign.yml).

Note

The workflow will attempt to set your name and email in Project.toml using your public GitHub profile information. You can review and change this in the generated Pull Request if needed.

Step 5: Review and Merge

• Go to the Pull requests tab, review the changes in the PR titled "Automate repository setup", and merge it.
• Once merged, the setup is complete.

Step 6: Final Steps

• First Release: You are now ready to make your first release (e.g., v0.1.0).
• Discussions: Enable discussions in your repository settings if you wish.

For more advanced customizations, such as adding a DOI badge or changing the documentation URL, please refer to the env: section in the .github/workflows/UpdateReadme.yml workflow.