From f884de8af9bf098524d41f272cd3d986e8ed9e5c Mon Sep 17 00:00:00 2001 From: fiona-naughton Date: Fri, 15 Nov 2024 20:50:22 +1100 Subject: [PATCH] add software dev intro skeleton --- .../source/software_development/community.rst | 14 ++++ .../software_development/documentation.rst | 36 ++++++++++ .../packaging-deployment-release.rst | 66 +++++++++++++++++++ .../software_development/testing-ci.rst | 41 ++++++++++++ .../version-control-hosting.rst | 62 +++++++++++++++++ .../software_development/writing-code.rst | 52 +++++++++++++++ docs/source/softwaredevguide.rst | 27 ++++++++ 7 files changed, 298 insertions(+) create mode 100644 docs/source/software_development/community.rst create mode 100644 docs/source/software_development/documentation.rst create mode 100644 docs/source/software_development/packaging-deployment-release.rst create mode 100644 docs/source/software_development/testing-ci.rst create mode 100644 docs/source/software_development/version-control-hosting.rst create mode 100644 docs/source/software_development/writing-code.rst create mode 100644 docs/source/softwaredevguide.rst diff --git a/docs/source/software_development/community.rst b/docs/source/software_development/community.rst new file mode 100644 index 00000000..1ef583af --- /dev/null +++ b/docs/source/software_development/community.rst @@ -0,0 +1,14 @@ +######### +Community +######### + +Estabilishing a community for your software package is an open-ended +task that can take many forms. GitHub provides may features. + +- bug reporting + feature requests (issue trackers) +- forum for asking/answering questsions +- instructions on how people can get involved in development + + + +- diff --git a/docs/source/software_development/documentation.rst b/docs/source/software_development/documentation.rst new file mode 100644 index 00000000..fad18f9a --- /dev/null +++ b/docs/source/software_development/documentation.rst @@ -0,0 +1,36 @@ +############# +Documentation +############# + +**could split this up** + +What is it? +----------- +- Information about your code + how to use it +- Important terms - types of documentation: README, docstrings, API, userguide +- Closely related: CHANGELOG, badges (e.g. code coverage, status), contribution instructions + +More detail: +- Things to cover + Installation instructions, description, example usage, tutorials/notebooks, + trouble shooting, function input/output + +Why is it important? +-------------------- +- README to provide a quick overview +- docstrings/API help you remember what your own code does, 'more advanced' users/contributors + know what they can do, easier to troubleshoot +- User Guides: more friendly to newcomers, explain *how* code works + + +How is it done? +--------------- +- Local docs vs. hosting online + Hosting directly from code vs. separate (e.g. mda docs vs. User Guide) +- README + markdown (+ display on GitHub) +- docstring conventions - what to cover + format (link) +- Sphinx/ReadTheDocs/rst (+ from GitHub) + Link to relevant parts of cookiecutter example + Quick summary of some particularly useful Sphinx things (toctree, autosummary, ...) + Link to relevant parts of cookiecutter example +- GitHub pages diff --git a/docs/source/software_development/packaging-deployment-release.rst b/docs/source/software_development/packaging-deployment-release.rst new file mode 100644 index 00000000..728326e7 --- /dev/null +++ b/docs/source/software_development/packaging-deployment-release.rst @@ -0,0 +1,66 @@ +################################### +Packaging, deployments and releases +################################### + +Packaging +========= +What is is? +----------- +- Group everything your code needs so it's easy for users to grab + install + the code, dependencies, license +- Important terms: 'source install', dependencies (+pinning), 'package distribution platforms' + 'package manager', (deployment, versioning, releases - expanded below) +- Highlight: a git repository vs. a repository of packages +- Relevant: dependencies - support windows + +Why is it important? +-------------------- +- specifying versions, installing these automatically ('resolve dependencies') + +How is it done? +--------------- +- Python package: __init__.py + Installable: pyproject.toml/(setup.py) +- PyPI + conda-forge + (basic overview how/links to the relevant pages) +Link to relevant cookiecutter bits + + +Licensing +========= +*take from existing license page* + +What is it? +----------- +- legal statement about who owns + who can use the code/how + +Why is it important? +-------------------- + +How is it done? +--------------- +- LICENSE file, link to licenses + + +Deployments and releases +======================== +What is it? +----------- +- A particular 'state' of a software package + making it available +- Important terms: version number+semantic versioning, release notes + +More details: +- What goes in release notes; CHANGELOG +- Not making 'breaking changes' straight away + notifying of upcoming changes +- when to make releases - stable release vs. nightly builds + +Why is it important? +-------------------- + +How is it done? +--------------- +- versioningit/versioneer +- e.g. using git tags + releasing w/ github + link to relevant sections of cookiecutter; MDA userguide +- Publishing new versions to PyPI/conda-forge; automatic pipelines +Links to relevant cookiecutter bits diff --git a/docs/source/software_development/testing-ci.rst b/docs/source/software_development/testing-ci.rst new file mode 100644 index 00000000..4da1ff74 --- /dev/null +++ b/docs/source/software_development/testing-ci.rst @@ -0,0 +1,41 @@ +################################## +Testing and continuous integration +################################## + +Testing +======= +What is it? +----------- +- Check that running a piece of code gives an expected result +- Important terms: regression tests/unit tests, 'code coverage' + +More detail: +- Things to cover: both 'good' and 'bad' data + +Why is it important? +-------------------- + +How is it done? +--------------- +- pytest, unittest + { some particular tips w/ pytest? assert } +- Where do tests 'live'? with the package (MDAKit cookie cutter) vs. separate (MDA) +- Running locally, running automatically -> GitHub actions + CI +- codecov (+ automating) + + +Continuous integration +====================== +What is it? +----------- +- Check that software still works in general (installation, pass tests) as + time progresses +- Related: 'upstream dependencies'+ keeping an eye on upcoming changes + +Why is it important? +-------------------- +- Both changes you make + that happen upstream can affect code in unexpected ways! + +How is it done? +--------------- +- GitHub actions + scheduling on push, at X time, etc diff --git a/docs/source/software_development/version-control-hosting.rst b/docs/source/software_development/version-control-hosting.rst new file mode 100644 index 00000000..0983810f --- /dev/null +++ b/docs/source/software_development/version-control-hosting.rst @@ -0,0 +1,62 @@ +#################################################### +Version control and distributed software development +#################################################### + +Version control +=============== +What is it? +----------- +- Keeping track of changes in files, manage how changes are combined +- Important terms: repository, branches, commit, merge + +More detail: +- branch naming 'conventions': main, develop, ... + +Why is it important? +--------------------- +- Work on multiple things/with multiple people +- Track who did what, when did things break, undo things + + +How is it done? +--------------- +git - but also mercurial + Quick summary cheatsheet: init, branch, checkout + add, commit, reset + + +Hosting a repository +==================== +*GitHub is suggested for MDAKits, since you'll need a GitHub account +to register a Kit, but not required.* + +What is it? +----------- +- Putting repositories where they can be accessed online +- Important terms: local vs remote, origin/upstream/fork/clone; pull requests+review +- Highlight: Git vs. GitHub + + +Why is it important? +-------------------- +- better sharability/accessibiltiy of the above +- can provide lots of ways to add/automate lots of things! e.g. see GitHub below + + +How is it done? +--------------- +GitHub - but also GitLab, BitBucket + Quick summary cheatsheet: clone, push, pull + Link to where we describe fork+clone+push+PR in examples? + + + +Overview of things you can do with GitHub +========================================= +(gather links to relevant sections) + +- Issues + Pull Requests (and can have templates for these) +- GitHub discussion +- git tags + releases +- GitHub actions: codecov, tests/CI, linters, ... +- documentation: readmes, tie into readthedocs, githubpages diff --git a/docs/source/software_development/writing-code.rst b/docs/source/software_development/writing-code.rst new file mode 100644 index 00000000..73ec0ae5 --- /dev/null +++ b/docs/source/software_development/writing-code.rst @@ -0,0 +1,52 @@ +##################### +Tips for writing code +##################### + +MDAnalysis is written largely in Python; it is likely (though not required) that +an MDAKit will be too. +We won't cover an introduction to writing with Python here (link out to Python resources), +but here are some tips for while you write! + + +Following a style guide +======================= +What is it? +----------- +- set of convetions for writing code +- Important terms: PEP8, Linters + +Why is it important? +-------------------- +- Keeps code readable - for both you + others + +How is it done? +--------------- +Linters: e.g. flake8, black, pylint; using w/ GitHub actions + (link to relevant part of cookiecutter example) + + + +Virtual Enviroments +=================== +What is it? +----------- +- collection of installed software/packages that can be easily switched between + + +Why is it important? +-------------------- +- have 'clean' starting environment, minimise conflicts +- work with test versions without affecting stable versions + + +How is it done? +--------------- +conda/mamba, virtual env + Quick summary cheatsheet: creating, updating, ctivating/inactivacing + + + +Misc. tips for writing code using MDAnalysis +============================================ +MDAnalysis API - e.g. AnalysisBase; util functions etc + diff --git a/docs/source/softwaredevguide.rst b/docs/source/softwaredevguide.rst new file mode 100644 index 00000000..5423155a --- /dev/null +++ b/docs/source/softwaredevguide.rst @@ -0,0 +1,27 @@ +########################################## +A (brief) overview on software development +########################################## + +This guide is intended to provide an introduction for scientists interested in +creating an MDAKit, who may not be familiar with software development terms and +best practices. +As such, it has an **MDAnalysis-centric perspective**, and will often list tools +and methods that are specific to Python packages. These do not represent the +the only way of doing things, nor are all MDAKits required to by pure Python +packages. +However, it is hoped this guide will still serve broadly as a general introduction +to soem basic concepts in software development. + + +Links to other resources: + - MolSSI + - etc + + +Contents: +- Writing Code +- Version control + distributed software development +- Documentation +- Testing and continous integration +- Packaging, deployments + releases +- Community resources