mirror of
https://github.com/slsdetectorgroup/aare.git
synced 2025-07-10 19:01:51 +02:00
Workflot and Philosophy
This commit is contained in:
5
.github/workflows/build_docs.yml
vendored
5
.github/workflows/build_docs.yml
vendored
@ -2,7 +2,10 @@ name: Build the package using cmake then documentation
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
push:
|
||||
pull_request:
|
||||
release:
|
||||
types:
|
||||
- published
|
||||
|
||||
|
||||
permissions:
|
||||
|
63
.github/workflows/manual_deploy_docs.yml
vendored
Normal file
63
.github/workflows/manual_deploy_docs.yml
vendored
Normal file
@ -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
|
||||
|
||||
|
||||
|
||||
|
34
docs/src/Philosophy.rst
Normal file
34
docs/src/Philosophy.rst
Normal file
@ -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.
|
@ -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**
|
||||
|
@ -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.
|
@ -63,5 +63,6 @@ AARE
|
||||
:caption: Developer
|
||||
:maxdepth: 3
|
||||
|
||||
Philosophy
|
||||
Workflow
|
||||
Tests
|
Reference in New Issue
Block a user