SO Developer Guide

General Advice

Contents:

• Introduction to the Developer Guide
  • Why have a Developer’s Guide and Style Guide?
• Copyright, Licensing, etc.
  • Introduction
  • Policy on Openly Contributed Code
  • Discussion
    • Importance of Licensing and Copyright
    • Copyright
    • Licensing
    • Public vs. Private Repositories
    • Acknowledgment Requirements
    • External Collaboration Opportunities
  • Copyright and License Cookbook
    • Stating Copyright
    • Declaring the License
    • Inherited Licenses
• Common Standards for Code and Process
  • Style and Technique
    • Style is not Personal
    • Behind every great writer is a great editor
  • Git and Github
    • Resources for beginners
    • Additional advice on git usage
    • Git Style Recommendations
    • The SO Github Organization
    • Repository Administration
  • Releases and Release Numbering
    • Semantic Versioning
  • Unit Testing
    • Designing good unit tests
• Code Documentation
  • Documentation System
    • sphinx
  • Plain-text documentation
• Python
  • Overview
  • Version Support
  • Style
    • Indentation
    • Line width
    • Naming Conventions
    • Typing
    • Ruff Config
  • Documentation of Code
    • docstrings
    • Inline Comments
  • Implementation Choices
  • Module Packaging
    • Pyproject file
    • develop vs. build+install
    • User override of compiler options and install locations
  • Unit Testing
    • unittest
    • Github Actions for Continuous Integration
  • Compiled Extensions
    • Numerical Data
    • Meson
    • Style in Mixed Language Codes
  • Tips for Successful Scientific Codes
    • Parameter Files
    • Command-Line Scripts
    • User Choice of Install Location, Compiler Choice, etc.
  • Automatic Semantic Versioning
    • Versioneer
• C/C++
  • Overview
  • Version Support
  • Style
    • Indentation
    • Line width
    • Naming Conventions
    • Header Files
    • Use of Language Features
    • Clang-format Config
  • Documentation of Code
  • Unit Testing
    • Github Actions for Continuous Integration
  • Automatic Semantic Versioning

Special Guidance for Domains

Contents:

• Special Guidance: DAQ
• Special Guidance: Instrument Testing Groups
  • Overview
  • Scope
  • Core Reference Codes
  • Provenance of Code and Data
    • “Provenance-Tracked” Results
    • Recording Provenance
    • Tool: Version Summarizer
    • Guidance: Jupyter notebooks
• Special Guidance: Pipeline Working Groups
• Special Guidance: Analysis Working Groups
  • General guidance
  • Core Codes
  • Codes on SO Github