Developer Documents for Version 0.2

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+# Title Formatting
+Please format your Pull Request title according to the Conventional Commits specification. This is crucial for automating our release process.
+
+Based on the changes in your PR, please use one of the following prefixes in your title:
+
+- fix: for a bug fix.
+
+Example: fix: correct user authentication flow
+
+- feat: for a new feature.
+
+Example: feat: add user profile page
+
+- For breaking changes, you must signify this in one of two ways:
+
+  - Append a ! after the type in the title.
+
+    Example: feat!: remove user endpoint
+
+  - Include a footer in your PR description below that starts with BREAKING CHANGE:.
+

.github/dependabot.yml

@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/CI.yml

@@ -0,0 +1,41 @@
+# name: CI
+# on:
+#   push:
+#     branches: 
+#       - main
+#     tags: ['*']
+#   pull_request:
+#   workflow_dispatch:
+# concurrency:
+#   # Skip intermediate builds: always.
+#   # Cancel intermediate builds: only if it is a pull request build.
+#   group: ${{ github.workflow }}-${{ github.ref }}
+#   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+# jobs:
+#   test:
+#     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }}
+#     runs-on: ${{ matrix.os }}
+#     timeout-minutes: 60
+#     permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
+#       actions: write
+#       contents: read
+#     strategy:
+#       fail-fast: false
+#       matrix:
+#         version:
+#           - '1.11'
+#           - '1.6'
+#           - 'pre'
+#         os:
+#           - ubuntu-latest
+#         arch:
+#           - x64
+#     steps:
+#       - uses: actions/checkout@v4
+#       - uses: julia-actions/setup-julia@v2
+#         with:
+#           version: ${{ matrix.version }}
+#           arch: ${{ matrix.arch }}
+#       - uses: julia-actions/cache@v2
+#       - uses: julia-actions/julia-buildpkg@v1
+#       - uses: julia-actions/julia-runtest@v1

.github/workflows/CompatHelper.yml

@@ -0,0 +1,16 @@
+name: CompatHelper
+on:
+  schedule:
+    - cron: 0 0 * * *
+  workflow_dispatch:
+jobs:
+  CompatHelper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pkg.add("CompatHelper")
+        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
+      - name: CompatHelper.main()
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia -e 'using CompatHelper; CompatHelper.main()'

.github/workflows/Documenter.yml

@@ -2,10 +2,9 @@ name: Documenter
 on:
   push:
     branches:
-      - master
       - main
-      - v0.2-main
-    tags: '*'
+    tags: 
+      - 'v*'
   pull_request:
     branches:
       - master

.github/workflows/HM_Bump_version.yml

@@ -0,0 +1,117 @@
+name: 'Propose Version Bump'
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches:
+      - main 
+
+jobs:
+  propose-bump:
+    # This job only runs when a PR is successfully merged.
+    if: github.event.pull_request.merged == true
+
+    runs-on: ubuntu-latest
+
+    steps:
+      # Step 1: Checkout the repository code.
+      - name: 'Checkout Repository'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # We need history to find the commit by its SHA
+          token: ${{ secrets.PAT_FOR_BUMP_PR }}
+
+      # Step 2: Get the merge commit message
+      - name: 'Get Merge Commit Message'
+        id: commit_message
+        run: |
+          # Use git log to get the full message of the exact merge commit SHA.
+          # The -n 1 flag ensures we only get one commit.
+          # The output is set for the next step to use.
+          MSG=$(git log --format=%B -n 1 ${{ github.event.pull_request.merge_commit_sha }})
+          echo "message<<EOF" >> $GITHUB_OUTPUT
+          echo "$MSG" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      # Step 3: Determine bump type and update the Project.toml file.
+      - name: 'Calculate Bump and Update Version File'
+        id: bump_logic
+        shell: python
+        run: |
+          import os
+          import re
+          import sys
+
+          # Read the commit message from the previous step's output
+          commit_message = os.environ['COMMIT_MESSAGE']
+
+          # Determine bump type based on the Angular Conventional Commit spec
+          bump_type = ''
+          first_line = commit_message.splitlines()[0]
+
+          if re.search(r'BREAKING CHANGE:', commit_message) or re.match(r'^\w+(\([\w-]+\))?!:', first_line):
+              bump_type = 'major'
+          elif re.match(r'^feat(\([\w-]+\))?:', first_line):
+              bump_type = 'minor'
+          elif re.match(r'^fix(\([\w-]+\))?:', first_line):
+              bump_type = 'patch'
+
+          if not bump_type:
+              print('No version bump required for this commit.')
+              print('::set-output name=bumped::false')
+              sys.exit(0)
+
+          print(f'Determined bump type: {bump_type}')
+
+          try:
+              with open('Project.toml', 'r+') as f:
+                  content = f.read()
+                  version_match = re.search(r'^version\s*=\s*\"(\d+)\.(\d+)\.(\d+)\"', content, re.M)
+
+                  if not version_match:
+                      print('Error: Could not find version in Project.toml')
+                      sys.exit(1)
+
+                  major, minor, patch = map(int, version_match.groups())
+
+                  if bump_type == 'major': major, minor, patch = major + 1, 0, 0
+                  elif bump_type == 'minor': minor, patch = minor + 1, 0
+                  elif bump_type == 'patch': patch += 1
+
+                  new_version = f'{major}.{minor}.{patch}'
+                  print(f'Bumping version to {new_version}')
+
+                  new_content = re.sub(r'^version\s*=\s*\".*\"', f'version = "{new_version}"', content, count=1, flags=re.M)
+
+                  f.seek(0)
+                  f.write(new_content)
+                  f.truncate()
+
+                  print(f'::set-output name=new_version::{new_version}')
+                  print('::set-output name=bumped::true')
+
+          except FileNotFoundError:
+              print('Error: Project.toml not found.')
+              sys.exit(1)
+        env:
+          # Pass the message from the "Get Merge Commit Message" step
+          COMMIT_MESSAGE: ${{ steps.commit_message.outputs.message }}
+
+      # Step 4: Create a new pull request with the version bump.
+      - name: 'Create Version Bump PR'
+        if: steps.bump_logic.outputs.bumped == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.PAT_FOR_BUMP_PR }}
+          commit-message: "chore: bump version to ${{ steps.bump_logic.outputs.new_version }}"
+          title: "chore: Propose version bump to ${{ steps.bump_logic.outputs.new_version }}"
+          body: |
+            This PR was automatically generated to propose the next version for the Julia package.
+
+            The recommended version bump is to **${{ steps.bump_logic.outputs.new_version }}**. This was determined based on the conventional commit message of the last merged PR.
+
+            Please review and merge to apply the version update.
+          branch: "chore/version-bump-${{ steps.bump_logic.outputs.new_version }}"
+          labels: 'automated-pr, version_update'
+          delete-branch: true

.github/workflows/HM_Changelog_update.yml

@@ -0,0 +1,51 @@
+name: Propose Changelog Update
+
+on:
+  # JuliaTagBot activated
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
+
+jobs:
+  propose-changelog:
+    # Only when TagBot is activated, change the CHANGELOG
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    runs-on: ubuntu-latest
+    steps:
+      # Step 1
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # All git history
+          fetch-depth: 0
+
+      # Step 2
+      - name: Generate cumulative CHANGELOG.md
+        id: changelog_generator
+        uses: TriPSs/conventional-changelog-action@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+        #   output-file: "CHANGELOG.md"
+          input-file: "CHANGELOG.md"
+          version-file: "./Project.toml"
+          skip-commit: true
+          skip-tag: true
+          git-push: false
+
+      # Step 3
+      - name: Create Pull Request with updated CHANGELOG.md
+        if: steps.changelog_generator.outputs.skipped == 'false'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.PAT_FOR_CHANGELOG }}
+          commit-message: "docs(changelog): update CHANGELOG.md"
+          title: "Docs: Update CHANGELOG.md for new release"
+          body: |
+            This PR was automatically generated to update the `CHANGELOG.md` file for the upcoming release.
+
+            Please review the changes and merge to trigger the final release.
+          # Branch for changelog
+          branch: "chore/update-changelog"
+          # If exist, update
+          delete-branch: true

.github/workflows/HM_TagBot.yml

@@ -0,0 +1,25 @@
+name: Run TagBot on Merge
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches:
+      - main 
+
+jobs:
+  tagbot:
+    # When pr is merged and the branch's name is 'chore/update-changelog'
+    if: github.event.pull_request.merged == true && github.event.pull_request.head.ref == 'chore/update-changelog'
+    runs-on: ubuntu-latest
+    steps:
+      # Step 1
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Step 2
+      - name: Run TagBot
+        uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/TagBot.yml

@@ -0,0 +1,31 @@
+name: TagBot
+on:
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
+    inputs:
+      lookback:
+        default: "3"
+permissions:
+  actions: read
+  checks: read
+  contents: write
+  deployments: read
+  issues: read
+  discussions: read
+  packages: read
+  pages: read
+  pull-requests: read
+  repository-projects: read
+  security-events: read
+  statuses: read
+jobs:
+  TagBot:
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

docs/make.jl

@@ -10,11 +10,19 @@ makedocs(
     sitename = "RLinearAlgebra",
     format = Documenter.HTML(
     collapselevel=1,
+    assets = String["custom_html.css"],
     ),
     plugins=[bib],
     modules = [RLinearAlgebra],
     pages = [
         "Home" => "index.md",
+        "Tutorials" => [
+            "Introduction" => "tutorials/introduction.md",
+            "Getting started" => "tutorials/getting_started.md"
+        ],
+        "Manual" => [
+            "Introduction" => "manual/introduction.md", 
+        ],
         "API Reference" => [
             "Compressors" => [
                 "Compressors Overview" => "api/compressors.md",
@@ -37,6 +45,16 @@ makedocs(
                                            ],
             ],
         ],
+        "Contributing" => [
+            "Contributing Overview" => "dev/contributing.md",
+            "Design of Library" => "dev/design.md",
+            "Checklists" => [
+                "dev/checklists.md", 
+                "Compressors" => "dev/checklists/compressors.md",
+                "Loggers" => "dev/checklists/loggers.md"
+            ],
+            "Style Guide" => "dev/style_guide.md",
+        ],
         "References" => "references.md",
     ]
 )
@@ -45,5 +63,7 @@ makedocs(
 # See "Hosting Documentation" and deploydocs() in the Documenter manual
 # for more information.
 deploydocs(
-    repo = "github.com/numlinalg/RLinearAlgebra.jl"
+    repo = "github.com/numlinalg/RLinearAlgebra.jl",
+    devbranch = "master", # master's newest commit will become dev
+    push_preview = true # pull requests to the master will become available
 )

docs/src/custom_html.css

@@ -0,0 +1,7 @@
+/* This file is aim to customize html format */
+
+/* Add margin at the beginning and the end of code blocks */
+li pre {
+  margin-top: 1em;
+  margin-bottom: 1em;
+}