Set up a new control-toolbox application or package

[ocots]

Set up a new control-toolbox application or package

This tutorial explains how to set up a new application or package in the control-toolbox ecosystem. We do not make any distinction between packages and applications concerning the setup since an application may become a package.

To find inspiration, you can visit some existing packages. For instance, check CTBase.jl or OptimalControl.jl. If you intend to add an application, please visit CalculusOfVariations.jl of Kepler.jl.

To make a new application / package, please follow these steps:

1. Create a new Github repository using CTApp.jl as template
2. Add keys and secrets
3. Replace name and owner
4. Update metadata
5. Activate discussions
6. Make your first release and deploy documentation
7. Enter into control-toolbox ecosystem

Step 1: Create a new Github repository using CTApp.jl as template

• Click on . This is equivalent to go to CTApp.jl repository, to click on "Use this template" and to click on "create a new repository".
• Enter the name, the description and choose the owner. We assume you provide

Owner	Name
my-owner	MyApp.jl

Hence, the application / package url should be:

https://github.com/my-owner/MyApp.jl

Warning

You must give a name with .jl suffix.

Step 2: Add keys and secrets

• Add a deploy key and a secret for the documentation with DocumenterTools.genkeys:

julia> ]
pkg> add DocumenterTools
julia> using DocumenterTools
julia> DocumenterTools.genkeys(user="my-owner", repo="MyApp.jl")
# follow instructions to add the deploy key and the secret
# then you can remove DocumenterTools
julia> ]
pkg> rm DocumenterTools

Warning

Don't forget to allow write access for the deploy key.

• Go to Settings > Secrets and variables > Actions and add a new repository secret for coverage. Give CODECOV_TOKEN as name. For the secret, if the owner is control-toolbox please create an issue asking to set up coverage and add @ocots to the assignees.

Step 3: Replace name and owner

Considering that the application / package name is MyApp.jl and the owner is my-owner, please update the following.

• Replace control-toolbox/CTApp.jl by my-owner/MyApp.jl in all the files.
• Replace all the remaining CTApp by MyApp in all the files.
• Rename the file src/CTApp.jl by src/MyApp.jl.

Note

You can remove the first sentence of the README.md file.

Tip

We recommend to use VSCode to develop. Visit our Developer guide for basic dev usage.

Step 4: Update metadata

• One can find templates for issues in .github/ISSUE_TEMPLATE. Please update assignees in markdown files from this directory. The assignees are notified when a new issue is created. You can put your github name for instance.
• Update authors in Project.toml.
• Update UUID in Project.toml with the output of

julia> string(UUIDs.uuid4())

Step 5: Activate discussions

Go to Settings and activate discussions.

Step 6: Make your first release and deploy documentation

• Give permissions to Github actions. Go to Settings > Actions > General, scroll to the end of the page and in Workflow permissions, select Read and write permissions and check Allow GitHub Actions to create and approve pull requests. Don't forget to save.
• Push all your changes to remote Github repository.
• Click on "create a new release". Then, click on "Choose a tag" and create the new tag v0.1.0. Give as title v0.1.0 and click on "Generate release notes". Now, you can click on "Publish release".

Note

When publishing a new release, please update the version in Project.toml to 0.1.1 for instance before creating the new release.

Note

In the README.md you can find two badges for the dev and stable documentations:
The dev documentation is updated each time you push changes to the main branch. The stable documentation is updated each time you make a new release.

Step 7: Enter into control-toolbox ecosystem

If you are developping an application, you may appear in top menu of https://control-toolbox.org. Please create an issue for asking and assign @ocots.

Tip

You are now ready to add code, unit tests and documentation. Visit our Developer guide for basic dev usage.

[jbcaillau]

super nice @ocots 👍🏽