Contribution Guidelines

💡 Contribution Guidelines

Before contributing, please carefully read the following documentation:
👉 Developer Guide

This guide is essential to understand how to work efficiently within the control-toolbox ecosystem.
It explains how to clone a repository, set up your development environment, run unit tests, and build the documentation.

---

📘 Overview of the Developer Guide

1. Clone the repository

   • Copy the repository URL (SSH or HTTPS) and run:

     cd ~/dev
     git clone the-url-you-have-copied

   • Example:

     cd ~/dev
     git clone git@github.com:control-toolbox/MyAwesomePackage.jl.git

2. Install VSCode

   • Install Visual Studio Code and the Julia extension.
   • Recommended extensions:
     • GitHub Actions
     • Markdown Preview for GitHub
     • Jupyter & Jupyter Renderers
     • Markdown Alerts

3. Run unit tests

   • In VSCode:

     using Pkg
     Pkg.activate(".")
     Pkg.test()

   • 👉 See Unit Testing to learn how to add your own tests.

4. Build the documentation

   • In the terminal:

     using Pkg
     Pkg.activate("docs")
     Pkg.develop(path=pwd()); include("docs/make.jl"); Pkg.rm("MyAwesomePackage")

   • This will generate the documentation in docs/build/index.html.
   • For more details, see Documenter.jl.

---

🧩 Contribution workflow

Once your environment is ready, follow the standard workflow:

Issue → Branch → Edit → Commit & Push → Draft PR → Review

---

1. 🪪 Pick an issue

• Go to the repository’s Issues page.
• Select an issue to work on or create a new one if needed.

  Each contribution must be linked to a corresponding issue.

---

2. 🌱 Create a branch from the issue

• From the issue page, click “Create a branch”.
  This automatically creates a branch linked to the issue.

  

---

3. 🧰 Update the code

• Clone (or fork) the repository if needed, then switch to your new branch.
• Apply your changes (e.g., remove a line, fix a bug, add a new feature).
• Make a clear commit with an explicit message, then push:

  git add .
  git commit -m "Fix typo in documentation"
  git push

---

4. 🔀 Open a Pull Request (PR)

• On GitHub, open a Pull Request from your branch.
• Convert it to a draft PR to indicate that work is in progress.
  This prevents premature merges and signals to reviewers that the PR is not yet ready.

---

5. 👀 Request a review

• Assign a reviewer, for instance @ocots or @jbcaillau.
• Mention them in a comment:

  @ocots please make a review
  

---

Important

📖 Read this before contributing:
👉 Developer Guide
It covers:

• How to clone a repository and run unit tests
• How to build documentation with Documenter.jl
• How to set up your VSCode environment
• Best development practices in the project

Note

🔍 Example:

• Pull Request #652 – OptimalControl.jl

Tip

🧠 Useful resources:

• Julia in VSCode
• Documenter.jl

---

✅ Summary

1. Read the Developer Guide
2. Create an issue and a dedicated branch
3. Edit the code and push your changes
4. Open a draft Pull Request
5. Request a review from a reviewer