Workflows as Runnable Docs

An analysis of workflow usage in the software development process.

What is a dev workflow?

When software developers refer to "workflow" in regards to a repository, they are usually discussing the recommended steps and instructions for setting up, building, and running the software project. For example, the workflow described in the README.md file helps other developers understand the necessary actions and dependencies required to use the codebase effectively. It's not unusual for workflows to include components of installation, configuration, building, testing, execution, deployment and troubleshooting of the codebase.

The benefits of using workflows

Using shared workflows in software development brings several benefits. Here are some of the key advantages:

  1. Collaboration: Enables simultaneous collaboration, reducing conflicts and promoting efficient communication and knowledge sharing.
  2. Consistency: Ensures adherence to standardized development practices, coding guidelines, and best practices, improving code quality and maintainability.
  3. Efficiency: Automates repetitive tasks, saving time and effort, while allowing developers to focus on critical aspects of development.
  4. Version Control: Integrates seamlessly with version control systems, facilitating effective version management, code review, and rollback strategies.
  5. Scalability: Provides a standardized approach for onboarding new team members and adapting to changing project requirements or development practices.
  6. CI/CD: Supports continuous integration and delivery practices, enabling automated build, test, and deployment processes for faster feedback and time-to-market.
Get started, run a README.md
$ brew install runme
$ npx runme
Runme for VS Code

Considerations in designing workflows

Software developers often face several challenges when using workflows to operate their codebase. Here are a few:

  1. Complexity: Implementing and managing workflows can be complex, especially in larger codebases with multiple interconnected components.
  2. Tooling and Infrastructure: Setting up the necessary tooling and infrastructure to support workflows can be challenging.
  3. Version Control and Collaboration: Coordinating changes and managing collaboration can be difficult when multiple developers are working on the same codebase.
  4. Testing and Quality Assurance: Ensuring code quality and reliability is crucial, but integrating testing and quality assurance processes into workflows can be challenging.
  5. Deployment and Rollbacks: Deploying code changes to production environments and handling rollbacks in case of issues are critical aspects of workflow management.
  6. Monitoring and Debugging: Once code is deployed, developers need to monitor the performance and behavior of their applications.
  7. Scalability and Performance: As the codebase and user base grow, developers need to ensure that workflows can handle increased demand and scale accordingly.
  8. Documentation and Knowledge Sharing: Clear documentation and knowledge sharing are essential for effective workflow management.

These challenges require developers to have a deep understanding of the codebase, the underlying technologies, and the specific requirements of the project. They need to continually refine and improve workflows to ensure efficient and reliable code operations.

Commonly used tools for operating workflows

Nearly every code repository has a set of markdown files, starting with the README.md. This is the simplest and most common manual tool (copy & paste) for organizing developer workflows. However, there are several popular tools used by software developers for managing and running workflows for their codebase, here are some common ones:

  1. Docker: Containerization platform for packaging applications and dependencies.
  2. Kubernetes: Container orchestration platform for automating deployment and management.
  3. Make: Build automation tool for defining dependencies and tasks.
  4. Gradle: Build automation tool with flexibility for defining custom workflows.
  5. Ansible: Automation platform for infrastructure provisioning and application deployment.
  6. GNU Parallel: Command-line tool for parallel execution of tasks.
  7. Apache Airflow: Platform for authoring and monitoring workflows and data pipelines.
  8. Git Hooks: Scripts triggered at specific points in the Git workflow for automation and custom actions.

If you use VS Code as your editor, it has a built-in runner for many of the above projects, but these are just a few examples of the tools available for managing and running workflows for codebases. It's important to consider the specific requirements of your project and team before choosing a tool, as each tool may have different strengths and capabilities.

Use Runme to manage your workflows

What is Runme?

Runme simplifies running commands in markdown files (e.g., README.md). It provides a command line binary for executing markdown workflows, a Github Action for CI/CD testing, and a VS Code extension for improved authoring, one-click command execution, and seamless service integrations.

Why should I use it?

Runme enhances your use of markdown files, offering greater convenience. While maintaining their original rendering for non-Runme users, markdown files can now provide an interactive notebook in VS Code or a feature-rich terminal experience for your project. Runme supports various tools for organizing and defining workflow tasks, as long as their dependencies are installed as part of the markdown workflow. This flexibility allows the use of different technologies within the workflow, enabling consumers to utilize their preferred tools. Crucially, your markdown remains within your codebase and can be tested against the associated code.

Key features

  • Runme is an open source project with community support.
  • It offers the easiest way to execute workflows using enhanced markdown.
  • Your markdown files remain within the repository.
  • Workflows can be created dynamically using command identifiers and categories.
  • Any tech/tools can be used in workflows.
  • Task behavior can be customized for intuitive execution.
  • Tasks interacting with common services or tools provide a better user experience.
  • Custom cell rendering improves output understanding.
  • Runme for VS Code enhances the markdown authoring experience.
  • Deep linking and cloning into a Runme notebook from the web is possible using VS Code.