fix: working on fixing github actions pipeline

.editorconfig

@@ -10,5 +10,9 @@ insert_final_newline = true
 charset = utf-8
 end_of_line = lf
 
+[{*.yml,*.yaml}]
+indent_style = space
+indent_size = 2
+
 [Makefile]
 indent_style = tab

.github/workflows/gh-pages.yml → .github/workflows/deploy-docs.yml

@@ -8,28 +8,34 @@ on:
   release:
     types: [created]
     branches:
-      - 'master'
+      - master
 
 jobs:
   build:
-    name: "Build docs"
+    name: Build docs
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/setup-python@v4
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
-    - name: "Install runtime dependencies in order to get package metadata"
-      run: "scripts/install"
-    - name: "Install deps and build with Sphinx"
-      run: make docs
-    - name: "Upload artifacts"
-      uses: actions/upload-pages-artifact@v1
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: pip install -r requirements.txt
+
+    - name: Build docs
+      run: scripts/build-docs.sh
+
+    - name: Upload artifacts
+      uses: actions/upload-pages-artifact@v3
       with:
         # Upload built docs
-        path: "./Documentation"
+        path: "./site"
   deploy:
-    name: "Deploy docs"
+    name: Deploy docs
     if: github.event_name == 'release' && github.event.action == 'published'
     needs: build
     runs-on: ubuntu-latest
@@ -42,6 +48,6 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
-    - uses: actions/deploy-pages@v1
+    - uses: actions/deploy-pages@v4
       id: deployment
       name: "Deploy to GitHub Pages"

.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish Package
+
+on:
+  # Only run when release is created in the master branch
+  release:
+    types: [created]
+    branches:
+      - 'master'
+
+jobs:
+  build:
+    name: Build distributable files
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: 'Checkout source repository'
+        uses: actions/checkout@v4
+        with:
+            fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+
+      - name: Install build dependencies
+        run: pip install build twine
+
+      - name: 'Build package'
+        run: scripts/build.sh
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          path: 'dist/*'
+
+  upload_pypi:
+    name: Upload packages
+    needs: ['build']
+    runs-on: 'ubuntu-latest'
+    if: github.event_name == 'release' && github.event.action == 'created'
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: artifact
+          path: dist
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: '__token__'
+          password: '${{ secrets.PYPI_API_TOKEN }}'

.github/workflows/python-package.yml → .github/workflows/tests.yml

@@ -1,7 +1,7 @@
 # This workflow will install Python dependencies, run tests and lint with a variety of Python versions
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
 
-name: Run Python tests
+name: Python package
 
 on:
   push:
@@ -31,24 +31,30 @@ jobs:
             experimental: true
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
             fetch-depth: 0
-      - uses: "actions/setup-python@v4"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
         with:
-          python-version: "${{ matrix.python-version }}"
-          cache: "pip"
+          python-version: ${{ matrix.python-version }}
+          cache: pip
           cache-dependency-path: |
-            requirements/*.txt
-            requirements/**/*.txt
-      - name: "Install dependencies"
-        run: "scripts/install"
-      - name: "Run linting checks"
-        run: "scripts/check"
-      - name: "Run tests"
-        run: "scripts/tests"
-      - name: "Enforce coverage"
-        uses: codecov/codecov-action@v3
+            requirements-*.txt
+            pyproject.toml
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Run linting checks
+        run: scripts/lint.sh
+
+      - name: Run tests
+        run: scripts/tests.sh
+
+      - name: Enforce coverage
+        uses: codecov/codecov-action@v4
         with:
             token: ${{ secrets.CODECOV_TOKEN }}
 

.pre-commit-config.yaml

@@ -9,7 +9,10 @@ repos:
       - id: check-yaml
       - id: check-toml
       - id: check-added-large-files
-
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v3.18.0
+    hooks:
+      - id: commitizen
   - repo: https://github.com/charliermarsh/ruff-pre-commit
     rev: v0.3.0
     hooks:

CHANGELOG.md

@@ -0,0 +1,4 @@
+
+## v0.2.0 (2024-03-02)
+
+## 0.1.0 (2023-01-10)

CODE_OF_CONDUCT.rst → CODE_OF_CONDUCT.md

@@ -1,5 +1,4 @@
-Code of Conduct
-===============
+# Code of Conduct
 
 Everyone interacting in the project's codebases, issue trackers, chat rooms,
 and mailing lists is expected to follow the Mode Code of Conduct.

CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing
+
+Contributions to mode are very welcome, feel free to open an issue to propose your ideas.
+
+To make a contribution please create a pull request.
+
+## Developing
+
+First it is recommended to fork this repository into your personal Github account then clone your freshly generated fork locally.
+
+### Setup environment
+
+Here are some guidelines to set up your environment:
+
+```sh
+$ cd mode/
+$ python -m venv env # Create python virtual environment, a `env/` has been created
+$ source env/bin/active # Activate the environment
+(venv) $ which pip # Ensure everything is well configured
+/some/directory/mode/env/bin/pip
+```
+
+### Install project dependencies
+
+```sh
+(venv) $ pip install -r requirements.txt
+Obtaining file:///some/directory/mode
+  Installing build dependencies ... done
+  Checking if build backend supports build_editable ... done
+  Getting requirements to build editable ... done
+  Installing backend dependencies ... done
+  Preparing editable metadata (pyproject.toml) ... done
+Ignoring pre-commit: markers 'python_version < "3.9"' don't match your environment
+...
+```
+
+This project apply some quality rules on code and commit, to enforce them at commit time you should install the [pre-commit](https://pre-commit.com/) hook:
+
+```sh
+(venv) $ pre-commit install
+pre-commit installed at .git/hooks/pre-commit
+```
+
+### Format & lint the code
+
+You can run the format script to make your change compliant:
+
+```sh
+(venv) $ ./script/format.sh
++ ruff format mode tests
+79 files left unchanged
++ ruff check mode tests --fix
+```
+
+_The script uses [ruff](https://github.com/astral-sh/ruff) & [mypy](https://mypy-lang.org/)._
+
+### Run tests
+
+A script is also available to run them:
+
+```
+(venv) $ ./scripts/tests.sh
++ pytest tests --cov=mode
+Test session starts (platform: linux, Python 3.12.2, pytest 8.1.1, pytest-sugar 1.0.0)
+...
+```
+
+_The script uses [pytest](https://docs.pytest.org/en/8.0.x/contents.html)._
+
+### Commit format
+
+Commit should be formatted following [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/).
+
+You can commit manually and respect the convention or you can use the cli to help you formatting correctly:
+
+```sh
+(venv) $ cz commit
+? Select the type of change you are committing docs: Documentation only changes
+? What is the scope of this change? (class or file name): (press [enter] to skip)
+ README
+? Write a short and imperative summary of the code changes: (lower case and no period)
+ correct spelling of README
+? Provide additional contextual information about the code changes: (press [enter] to skip)
+
+? Is this a BREAKING CHANGE? Correlates with MAJOR in SemVer No
+? Footer. Information about Breaking Changes and reference issues that this commit closes: (press [enter] to skip)
+
+
+docs(README): correct spelling of README
+```
+
+## Documentation
+
+To be able to run the documentation locally you should setup your environment and install dependencies, if not already you can read the two first part of the Developing section.
+
+```sh
+(venv) $ mkdocs serve
+INFO    -  Building documentation...
+INFO    -  Cleaning site directory
+INFO    -  Documentation built in 1.78 seconds
+INFO    -  [19:38:48] Watching paths for changes: 'docs', 'mkdocs.yml'
+INFO    -  [19:38:48] Serving on http://127.0.0.1:8000/
+```
+
+Then, you can browse the documentation on http://127.0.0.1:8000.
+
+## Maintainers
+
+### Publish a new release
+
+1. First create a new tag and update changelog
+
+```sh
+(venv) $ ./scripts/bump.sh
++ cz bump --changelog
+bump: version 0.2.0 → 0.2.1
+tag to create: 0.2.1
+increment detected: PATCH
+
+[master b35722f] bump: version 0.2.0 → 0.2.1
+ 2 files changed, 2 insertions(+), 1 deletion(-)
+
+...
+
+Done!
+```
+
+!!! note
+    If this pass it will automatically push the commit and tags to the remote server, you may want to use `cz bump --changelog --dry-run` to check generated changes.
+
+2. Then after ensuring github pass you could publish the release via the Github interface. (An action will triggered and will publish the package to pypi and documentation to the Github pages).