Workflot and Philosophy

.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:

.github/workflows/manual_deploy_docs.yml

@@ -0,0 +1,63 @@
+name: Deploy docs manually
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [ubuntu-latest, ] 
+        python-version: ["3.12",]
+
+    runs-on: ${{ matrix.platform }}
+
+    defaults:
+      run:
+        shell: "bash -l {0}"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get conda
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+          environment-file: etc/dev-env.yml
+          miniforge-version: latest
+          channels: conda-forge
+          conda-remove-defaults: "true"
+
+      - name: Build library 
+        run: |
+            mkdir build 
+            cd build 
+            cmake .. -DAARE_SYSTEM_LIBRARIES=ON -DAARE_DOCS=ON 
+            make -j 2 
+            make docs
+
+      - name: Upload static files as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3 
+        with:
+         path: build/docs/html/
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+
+
+

docs/src/Philosophy.rst

@@ -0,0 +1,34 @@
+****************
+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 due so changes 
+in the API. 
+
+
+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.
+
+
+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

@@ -2,7 +2,64 @@
 Workflow
 ****************
 
-We test the code both from the C++ and Python API. By default only tests that does not require image data is run. 
+This page describes how we develop aare. 
 
-github centric
-~~~~~~~~~~~~~~~~~~
+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.
+
+
+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
+~~~~~~~~~~~~~~~~~~
+
+Feature: 
+
+#. Create a new issue for the feature (label feature)
+#. Create a new branch from main. 
+#. Implement the feature including test and documentation.
+#. 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**
+#. 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.
+#. Create the release in GitHub describing the new features and bug fixes.
+#. CI makes magic.

docs/src/index.rst

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