Skip to content

Contributing to Control-lab-ly

Thank you for considering contributing to the Control-lab-ly project! We welcome contributions of all kinds, including bug fixes, new features, documentation improvements, and more. This document outlines the guidelines and best practices for contributing to ensure a smooth and collaborative process.

Table of Contents

  1. Code of Conduct
  2. Getting Started
  3. How to Contribute
  4. Reporting Issues
  5. Submitting Code Changes
  6. Improving Documentation
  7. Code Style Guidelines
  8. Testing Your Changes
  9. Pull Request Process

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Getting Started

  1. Fork the Repository: Create a fork of the repository on GitHub.
  2. Clone Your Fork: Clone your fork to your local machine: 
    git clone https://github.com/[your-username]/control-lab-ly.git
  3. Set Up the Environment:
  4. Install the required dependencies: 
    pip install -r dev/requirements_all.txt dev/requirements_dev.txt
  5. For documentation contributions, install additional dependencies: 
    pip install -r requirements_docs.txt
  6. Create a Branch: Create a new branch for your changes: 
    git checkout -b feature/[your-feature-name]

How to Contribute

Reporting Issues

If you encounter a bug or have a feature request, please open an issue on GitHub. Include the following: - A clear and descriptive title. - Steps to reproduce the issue (if applicable). - Expected and actual behavior. - Any relevant logs, screenshots, or code snippets.

Submitting Code Changes

  1. Follow the Code Style Guidelines.
  2. Ensure your changes are well-documented.
  3. Write tests for your changes (if applicable).
  4. Commit your changes with a descriptive message: 
    git commit -m "Add feature: description of the feature"
  5. Push your branch to your fork: 
    git push origin feature/[your-feature-name]
  6. Open a pull request (PR) on the main repository.

Improving Documentation

We value clear and comprehensive documentation. To contribute: - Add docstrings directly into the classes, methods, and functions you write, using Google Style Python Docstrings. - Update or add content in the docs/ folder. - Follow the existing style and structure of the documentation. - Use Markdown for text-based documentation. - Preview your changes locally using mkdocs: 

mkdocs serve

Code Style Guidelines

To be updated

Testing Your Changes

  1. Write unit tests for your changes in the tests/ directory.
  2. Run the test suite using tox: 
    tox
    This will automatically create isolated environments and run pytest in each environment specified in the tox.ini file.
  3. To run tests for a specific environment, use: 
    tox -e py310
    Replace py310 with the desired environment.
  4. Ensure all tests pass before submitting your changes.

Pull Request Process

  1. Ensure your branch is up-to-date with the dev-v2-x-x branch (appropriate upcoming version number): 
    git fetch upstream
git merge upstream/dev-v2-x-x
  2. Address any merge conflicts.
  3. Provide a clear and concise description of your changes in the PR.
  4. Link any related issues in the PR description.
  5. Wait for a review from the maintainers.
  6. Address any feedback provided during the review process.

Thank you for contributing to Control-lab-ly! Your efforts help make this project better for everyone.