Added branching strategy etc. to docs (#191)

Added a section on the ideas behind the library and also explaining the
branching strategy.

---------

Co-authored-by: Dhanya Thattil <dhanya.thattil@psi.ch>

.github/workflows/build_docs.yml

@@ -2,7 +2,10 @@ name: Build the package using cmake then documentation
 
 on:
   workflow_dispatch:
-  push:
+  pull_request:
+  release:
+    types:
+      - published
     
 
 permissions:
@@ -55,7 +58,7 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build
-    if: github.event_name == 'release' && github.event.action == 'published'
+    if: (github.event_name == 'release' && github.event.action == 'published') || (github.event_name == 'workflow_dispatch' )
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

RELEASE.md

@@ -0,0 +1,22 @@
+# Release notes
+
+
+### head
+
+Features:
+
+- Cluster finder now works with 5x5, 7x7 and 9x9 clusters
+
+
+### 2025.05.22
+
+Features:
+
+- Added scurve fitting
+
+Bugfixes:
+
+- Fixed crash when opening raw files with large number of data files
+
+
+

docs/src/Philosophy.rst

@@ -0,0 +1,47 @@
+****************
+Philosophy
+****************
+
+
+Fast code with a simple interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Aare should be fast and efficient, but also easy to use. We strive to keep a simple interface that feels intuitive. 
+Internally we use C++ for performance and the ability to integrate the library in other programs, but we see most 
+users using the Python interface. 
+
+Live at head
+~~~~~~~~~~~~~~~~~~
+
+As a user of the library you should be able to, and is expected to, use the latest version. Bug fixes will rarely be backported
+to older releases. By upgrading frequently you will benefit from the latest features and minimize the effort to maintain your scripts/code 
+by doing several small upgrades instead of one big upgrade.
+
+API
+~~~~~~~~~~~~~~~~~~
+
+We aim to keep the API stable and only break it for good reasons. But specially now in the early stages of development
+the API will change. On those occasions it will be clearly stated in the release notes. However, the norm should be a 
+backward compatible API.
+
+Documentation
+~~~~~~~~~~~~~~~~~~
+
+Being a library it is important to have a well documented API. We use Doxygen to generate the C++ documentation
+and Sphinx for the Python part. Breathe is used to integrate the two into one Sphinx html site. The documentation is built
+automatically on release by the CI and published to GitHub pages. In addition to the generated API documentation,
+certain classes might need more descriptions of the usage. This is then placed in the .rst files in the docs/src directory.
+
+.. attention::
+
+    The code should be well documented, but using descriptive names is more important. In the same spirit
+    if a function is called `getNumberOfFrames()` you don't need to write a comment saying that it gets the 
+    number of frames.
+
+
+Dependencies
+~~~~~~~~~~~~~~~~~~
+
+Deployment in the scientific community is often tricky. Either due to old OS versions or the lack of package managers. 
+We strive to keep the dependencies to a minimum and will vendor some libraries to simplify deployment even though it comes
+at a cost of build time.

docs/src/Requirements.rst

@@ -2,18 +2,21 @@ Requirements
 ==============================================
 
 - C++17 compiler (gcc 8/clang 7)
-- CMake 3.14+
+- CMake 3.15+
 
 **Internally used libraries**
 
 .. note ::
 
-    These can also be picked up from the system/conda environment by specifying:
+    To save compile time some of the dependencies can also be picked up from the system/conda environment by specifying:
     -DAARE_SYSTEM_LIBRARIES=ON during the cmake configuration.
 
-- pybind11
+To simplify deployment we build and statically link a few libraries.
+
 - fmt
+- lmfit - https://jugit.fz-juelich.de/mlz/lmfit
 - nlohmann_json
+- pybind11
 - ZeroMQ
 
 **Extra dependencies for building documentation**

docs/src/Workflow.rst

@@ -0,0 +1,86 @@
+****************
+Workflow
+****************
+
+This page describes how we develop aare. 
+
+GitHub centric
+~~~~~~~~~~~~~~~~~~
+
+We use GitHub for all development. Issues and pull requests provide a platform for collaboration as well
+as a record of the development process. Even if we discuss things in person, we record the outcome in an issue.
+If a particular implementation is chosen over another, the reason should be recorded in the pull request.
+
+
+Branches
+~~~~~~~~~~~~~~~~~~
+
+We aim for an as lightweight branching strategy as possible. Short-lived feature branches are merged back into main. 
+The main branch is expected to always be in a releasable state. A release is simply a tag on main which provides a
+reference and triggers the CI to build the release artifacts (conda, pypi etc.). For large features consider merging
+smaller chunks into main as they are completed, rather than waiting for the entire feature to be finished. Worst case 
+make sure your feature branch merges with main regularly to avoid large merge conflicts later on.
+
+.. note::
+
+    The main branch is expected to always work. Feel free to pull from main instead of sticking to a 
+    release
+
+
+Releases
+~~~~~~~~~~~~~~~~~~
+
+Release early, release often. As soon as "enough" new features have been implemented, a release is created.
+A release should not be a big thing, rather a routine part of development that does not require any special person or
+unfamiliar steps.
+
+
+
+Checklists for deployment
+~~~~~~~~~~~~~~~~~~
+
+**Feature:**
+
+#. Create a new issue for the feature (label feature)
+#. Create a new branch from main.
+#. Implement the feature including test and documentation
+#. Add the feature to RELEASE.md under head
+#. Create a pull request linked to the issue
+#. Code is reviewed by at least one other person
+#. Once approved, the branch is merged into main
+
+
+**BugFix:**
+
+Essentially the same as for a feature, if possible start with
+a failing test that demonstrates the bug.
+
+#. Create a new issue for the bug (label bug)
+#. Create a new branch from main.
+#. **Write a test that fails for the bug**
+#. Implement the fix
+#. **Run the test to ensure it passes**
+#. Add the bugfix to RELEASE.md under head
+#. Create a pull request linked to the issue.
+#. Code is reviewed by at least one other person
+#. Once approved, the branch is merged into main
+
+**Release:**
+
+#. Once "enough" new features have been implemented, a release is created
+#. Update RELEASE.md with the tag of the release and verify that it is complete
+#. Create the release in GitHub describing the new features and bug fixes
+#. CI makes magic
+
+
+**Update documentation only:**
+
+.. attention::
+
+    It's possible to update the documentation without changing the code, but take
+    care since the docs will reflect the code in main and not the latest release.
+
+#. Create a PR to main with the documentation changes
+#. Create a pull request linked to the issue.
+#. Code is reviewed by at least one other person
+#. Once merged you can manually trigger the CI workflow for documentation

docs/src/index.rst

@@ -63,4 +63,6 @@ AARE
     :caption: Developer
     :maxdepth: 3
     
+    Philosophy
+    Workflow
     Tests