diff --git a/docs/posts/repository_setup.md b/docs/posts/repository_setup.md index e3feec5..ee1356b 100644 --- a/docs/posts/repository_setup.md +++ b/docs/posts/repository_setup.md @@ -1,27 +1,57 @@ --- date: 2024-05-01 -draft: true +draft: false categories: - cicd authors: - jev --- -# Let's Dive In: Setting Up Your Software Project Right -As Aristotle famously said, 'Well begun is half done.' This rings especially true when setting up a new software project. In this post, I'll walk you through the organization of the `roxbot` repository, explain the necessity of Continuous Integration (CI), and demonstrate how it can be seamlessly integrated with powerful automation tools. + +# Well begun is half done + +As Aristotle famously said, "Well begun is half done." This is particularly true when starting a new software project. In this post, I'll explain why Continuous Integration (CI) is crucial in modern software development, especially in complex fields like robotics. We'll also look at how CI/CD principles are implemented in the `roxbot` repository, providing practical insights and inviting you to explore the repository's code for more details. -Establishing a project with a modern CI/CD workflow is arguably one of the most challenging yet crucial tasks for developers, particularly in the field of robotics. To echo the humorous yet poignant words of Homer Simpson, 'If something is hard to do, then maybe it's not worth doing.' This sentiment often leads novice developers to bypass proper setup and dive straight into coding. While this approach might suffice for small projects, it quickly becomes unsustainable for larger ones. Developers find themselves bogged down with managing development environments across different systems, struggling to keep the documentation updated—if it exists at all—and spending the majority of their time simply trying to prevent their software from collapsing. +## Why Is CI Crucial? + +Setting up a CI/CD workflow can be daunting, especially in robotics. Homer Simpson humorously said, "If something is hard to do, then maybe it's not worth doing." However, adopting this mindset can lead to significant challenges in larger projects, such as inconsistent environments, outdated documentation, and unstable software. Here’s why CI/CD is essential: + +1. **Consistent Build and Test Environments**: CI/CD standardizes environments across all development stages, crucial in robotics where diverse tools and packages are used. + +2. **Enhanced Code Quality**: CI automates testing to ensure new code integrates well with the existing codebase, catching issues early to prevent real-world problems. + +3. **Reduced Deployment Risk**: Automated tests in production-like environments decrease the likelihood of failures and enhance safety when deploying software. + +## How We Implement CI/CD in `roxbot` + +!!! note + Setting up CI/CD properly takes effort and time; getting it 'fairly OK' is achievable, but perfecting it requires considerable work. As a developer, I aim to spend most of my time building functionality, not endlessly polishing my CI/CD environment—which could easily become a full-time job. You'll likely find many areas for improvement in `roxbot`'s CI/CD, as I capped the setup time at 4 hours. In my experience, CI/CD can *always* be improved, and contributions are welcome! + +- **Docker Environments**: + - **Development Image (`dev`)**: Managed via `docker/dev/Dockerfile`, includes comprehensive tools for development. + - **Continuous Integration Image (`ci`)**: Managed via `docker/ci/Dockerfile`, designed for reliable and clean testing. + +- **GitHub Actions**: Automation is managed through actions configured in `.github/workflows/build-images.yml` for building and hosting the `dev` image. + +- **VSCode DevContainer**: Development setup is streamlined using the configuration in `.devcontainer/devcontainer.json`. + +- **Hosting Images on GitHub**: Docker images are hosted using GitHub Packages as part of the workflow defined in `.github/workflows/build-images.yml`. -Three main reasons why CI/CD is crucial for robotics development are: +- **Configuration with `pyproject.toml`**: + - `ruff` linter to maintain high code quality and consistency across the project. + - `mypy` typechecker enhancing code reliability by catching type errors before runtime. + - `pytest` with coverage reports. See which lines of code escaped the tests. +- **Task automation with `invoke`**: a modern, pythonic way of scripting. The tasks are defined in `tasks.py`. Run `invoke --help` for more. -1. **Enhanced Code Quality**: Continuous Integration helps ensure that all new code integrates smoothly with existing code, automating testing to detect and fix issues early, which is crucial in robotics where bugs can have serious physical repercussions. +- **Building Documentation with MkDocs**: Documentation is automatically built and updated using MkDocs, configured in `mkdocs.yml`. -2. **Reduced Deployment Risk**: Automated pipelines test the software in environments that mimic production closely, which is critical in robotics to prevent errors that could cause operational failures or safety issues. +This toolset not only solves the "It works on my machine" problem but also ensures a high level of task automation, saving time for actual software deveopment. -3. **Consistent Build and Test Environments**: CI/CD maintains uniform environments throughout the development cycle, crucial for robotics development where differences in hardware and software configurations can lead to significant discrepancies in behavior and performance. +Explore the repository to see how these features are implemented and consider integrating them into your own projects. -In the following sections, we'll explore how the roxbot project leverages CI/CD pipelines not only to automate mundane tasks but also to ensure that the software remains robust and maintainable over time. Stay tuned as we delve into a world where efficiency meets quality in software development. +!!! tip + Manually setting up a repository for each new project can take a lot of time and result in many different structures. To aid this, there is an excellent tool called [cookiecutter](https://github.com/cookiecutter/cookiecutter). There are many templates available to set up a repo in less than a minute! One of my own templates that I often use is [python-microservice](https://gitlab.com/roxautomation/templates/python-microservice/). Want to go even further? Take a look at [cruft](https://cruft.github.io/cruft/) - a tool to update repositories to their templates. diff --git a/mkdocs.yml b/mkdocs.yml index 9461896..154154a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,6 +30,9 @@ plugins: markdown_extensions: - pymdownx.snippets + - admonition + - pymdownx.details + - pymdownx.superfences - pymdownx.superfences: custom_fences: - name: mermaid