MDAnalysis · fiona-naughton · Nov 15, 2024
diff --git a/docs/source/software_development/community.rst 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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