Research Software Engineering Guidelines Documents

Welcome to the University of Washington Scientific Software Engineering Center (UW SSEC) Research Software Engineering (RSE) Guidelines repository. This comprehensive collection of tutorials, guides, and best practices is designed to help researchers, software engineers, and developers adopt modern software engineering practices for scientific computing and research projects.

These guidelines are not meant to be an exhaustive knowledge base, but rather a curated set of quick guides and practical tutorials to jumpstart your RSE journey, whether you're just getting started or looking to level up your skills.

The UW Scientific Software Engineering Center (SSEC) at the eScience Institute leverages local software engineering talent to advance scientific frontiers. SSEC is a diverse team of software engineers who work with UW scientists on impactful research projects, infusing them with software industry best practices and delivering open source, reusable software that accelerates research in areas like climate, health, energy, and basic science.

Led by Director David Beck and Head of Engineering Vani Mandava, SSEC is structured around applied machine learning for science, cloud computing and data management, and community building around scientific software.

The full documentation is available at: https://rse-guidelines.readthedocs.io/

The documentation is organized into the following main sections:

Core concepts and tools that every research software engineer should know:

• Git and GitHub for Collaboration - Version control, collaborative workflows, pull requests, and the fork-and-pull model for open source development
• Conventional Commits - Structured commit message conventions for clear, machine-readable git history
• Testing and Debugging - Debugging techniques with VS Code, unit testing, and Jupyter notebook debugging
• Code Sharing and Deployment - GitHub Actions for CI/CD, GitHub Codespaces for collaborative development environments
• Computing & Development Environments:
  • Docker - Containerization basics
  • Conda/Mamba - Python environment management
  • Pixi - Modern, fast, project-centric package manager (evolution of conda)
  • Notebooks & Interactive Environments - Jupyter and interactive computing
• AI for Software Engineering:
  • GitHub Copilot - AI-powered coding assistant setup and best practices
  • Working with ChatGPT - Using large language models for coding tasks
  • Local LLMs - Running language models locally for privacy and offline use

More specialized topics for experienced developers:

• Profiling - CPU and memory profiling tools for Python (cProfile, Scalene, Memray, and more)
• Deployment Strategies & Tools:
  • Docker Advanced - Advanced containerization techniques
  • Kubernetes - Container orchestration
  • Cloud Infrastructure and Services - Cloud deployment strategies

Modern application development technologies:

• Frontend:
  • Flutter - Cross-platform mobile and web application development

• Python Guidelines - Python-specific best practices and links to the Scientific Python Library Development Guide

Step-by-step hands-on tutorials:

• Git, GitHub, and Conventional Commits Tutorial - Comprehensive tutorial combining Git workflows, forking, pull requests, and conventional commits for effective collaboration

1. New to Research Software Engineering? Start with the documentation home page and explore the fundamentals section
2. Need to collaborate on code? Check out the Git and GitHub guide
3. Setting up a development environment? Learn about Pixi for modern Python environment management
4. Want to use AI tools? See our GitHub Copilot guide
5. Performance issues? Dive into Profiling to identify bottlenecks

• Browse the organized documentation on our ReadTheDocs site
• Use the navigation sidebar to explore topics by category
• Each guide includes practical examples, code snippets, and external resources
• Tutorials provide hands-on exercises to practice new skills

We welcome contributions! If you'd like to improve these guidelines or add new content:

1. Fork this repository
2. Create a feature branch following the guidelines in our Git and GitHub documentation
3. Follow conventional commits for your commit messages
4. Submit a pull request

The documentation is built using MkDocs with the Material theme. To build locally:

# Install dependencies using pixi (recommended)
pixi install

# Serve the documentation locally
pixi run mkdocs serve

# Or using pip
pip install mkdocs mkdocs-material mkdocs-jupyter awesome-pages mkdocs-llms-txt-plugin mike
mkdocs serve

The documentation will be available at http://127.0.0.1:8000/.

This documentation is provided under an open source license. Please refer to individual files for specific license information.

For questions or suggestions, please open an issue or contact the UW SSEC team through the eScience Institute.

Happy coding, and welcome to modern research software engineering!