Wiki contents - cma-open/cmatools GitHub Wiki

Overview

  • Purpose and content

    • A description of the purpose of both the cma-tools and cma-science repos and how they can be used as templates to create new code repos

  • Wiki contents

    • This page

User Guide

  • Installation and use
    • A link to the main documentation page where the User Guide and API documentation pages can be found

Developer's Guide

This section contains pages targeted at developers working on the project or potential contributors to those projects based on the repo templates

  • Setup for development

    • Full, repeatable instructions for setting up the system ready for development or testing
    • This should include any specific settings or configurations for developer or tester tools

  • System tests

    • How to run and re-un the system tests post installation and during development

  • Test plan

    • An outline of the test plan strategy to be used by system testers and developers to ensure high quality code

  • Uninstall

    • Notes on the process and helper scripts used to uninstal and re-install the system for testing

  • PyCharm setup

    • Notes on setting up PyCharm for development use

  • Branch based development

    • Detail of the method used to create feature branches and the process for allowing these to be merged into main / master

  • Code review and Pull requests

    • Steps that are followed for code review, when a modular piece of work in ready to be merged to main / master

  • Code quality and style

    • Targets for developing high quality code
    • Record of code style format

  • Workflows (pipelines)

    • Details of the GitHub workflow actions that are used to automate:
      • Project documentation
      • Code release and version
      • Testing

  • Creating a release

    • Process for manual or automated code release

Template use

  • Template use
    • Notes on creating a new project using the repo templates
    • This is WIP, and will cover:
      • Creating the GitHub pages branch
      • Wiki setup and content

Project management

Notes relating to general project management, rather than code development

  • Software requirements

    • Example categories used to detail the software requirements to which the development team are working

  • cmascience requirements

    • The software requirements used to build the cmascience python package

  • cmatools requirements

    • The software requirements used to build the cmatools python package

  • System architecture

    • Using a system architecture terminology and associated diagrams to help design and build the system

  • GitHub setup and use

    • A record of how GitHub tools are used for general project management accross Agile "Sprints"

Python package development

Notes relating to the generic development of Python packages. These pages also give specific examples for the current repo.

  • Assumptions and context

    • The context and any assumptions being made about the software system being created

  • Development and run environment

    • The environment in which the system will be developed, tested and run. This includes any considerations about system dependencies, development replicability and system versioning.

  • Package directory structure

    • Listing of the key directories within the template python package and notes on content, format and options

  • Naming conventions

    • Description and examples of python naming conventions, e.g for functions, classses, variables

  • Software versions

    • Outline of software system versioning

  • Dataset versions

    • Comparing software system and dataset version conventions

  • Command line tools

    • A description of options for creating command line python tools and how these can be configured via argparse and entry points in the setup.py module.

  • Testing

    • An outline of the main types of test that are expected to be covered by a python package development test plan

  • Running an application

    • Overview of different methods available to run a python system, from simple module calls to installed command line applications.

  • Sphinx documention

    • Description of the setup of the Sphinx documentation pages and an outline of the steps required for editing and setup.

  • Sharing a python package

    • Listing of the options for sharing a python package for use either by end users or to be installed and used by other packages

  • Linking packages

    • Details how a package can be installed as a dependency requirement of another python package.

  • Multi package repos

    • The pros and cons of hosting single versus multiple python packages within a single repo.

Appendix

A range of supplementary info, resource links and decision and learning logs

  • Terminology

    • Definition of key terms

  • Package directory structure

    • Resource links

  • Naming conventions

    • Resource links

  • Testing

    • Resource links

  • Config log

    • List of config options selected for associated packages, testing, etc during development

  • Decision log

    • A record of key decisions made during development of the system

  • Learning log

    • Key lessons and experiences learned during system development