Chore/auto versioning workflow (fmilthaler#111)

This adds another GitHub workflow `AutoVersion` for automated
versioning.

`AutoVersion` is triggered after PR is merged into `master` or
`develop`. It then determines whether the version is a patch or minor
change based on the source branch name.
- `patch`: version number increase of `0.0.1`
- `minor`: version number increase of `0.1.0`
- `major`: version number increase of `1.0.0`

The branch name patterns that are currently matched to one of the above
are:
- `patch`: one of `chore/`, `refactor/`, `bugfix/`
- `minor`: `feature/`
- `major`: None (not planned at the moment)

Note: the patterns mentioned above, e.g. `bugfix/` must be the prefix of
the branch name. If you are working on a bugfix to fix a print statement
of the portfolio properties, your branch name should be something like
`bugfix/print-statement-portfolio-properties`. For the automated
versioning to work, the branch name is required to **start with**
`bugfix/` or one of the other above mentioned patterns.

For now, the release number is also updated every time the version
number is updated. This practically renders the release number
redundant, but it is used in the README.md to show the current release
number on PyPI.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: fmilthaler

.github/workflows/auto-format.yml

@@ -1,4 +1,5 @@
-name: AutoUpdateFormatting
+name: AutoFormatting
+
 on:
   push:
     branches:
@@ -22,7 +23,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.10'  # Specify the desired Python version
+          python-version: '3.10'
 
       - name: Install dependencies
         run: |
@@ -31,15 +32,15 @@ jobs:
       - name: Updating README files
         id: update_readme
         run: |
-          bash scripts/update-readme.sh
-          bash scripts/auto-commit.sh "Updating README files"
+          bash scripts/update_readme.sh
+          bash scripts/auto_commit.sh "Updating README files"
         continue-on-error: true
 
       - name: Code formatting and committing changes
         id: code_format
         run: |
-          bash scripts/auto-format.sh
-          bash scripts/auto-commit.sh "Automated formatting changes"
+          bash scripts/auto_format.sh
+          bash scripts/auto_commit.sh "Automated formatting changes"
         continue-on-error: true
 
       - name: Push changes

.github/workflows/auto-versioning.yml

@@ -0,0 +1,49 @@
+name: AutoVersion
+on:
+  pull_request:
+    types:
+      - closed
+
+env:
+  SOURCE_BRANCH: ${{ github.head_ref }}
+  BASE_BRANCH: ${{ github.base_ref }}
+
+jobs:
+  auto-versioning:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.pull_request.merged == true && (github.event.pull_request.base.ref == 'master' || github.event.pull_request.base.ref == 'develop') }}
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ github.base_ref }}
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements_ci.txt  # Adjust as per your project's requirements
+
+      - name: Automated versioning and committing changes
+        id: auto_version
+        run: |
+          python scripts/update_version.py ${{ env.BASE_BRANCH }} ${{ env.SOURCE_BRANCH }}
+          bash scripts/auto_commit.sh "Automated version changes"
+        continue-on-error: true
+
+      - name: Updating README files
+        id: update_readme
+        run: |
+          bash scripts/update_readme.sh
+          bash scripts/auto_commit.sh "Updating README files"
+        continue-on-error: true
+
+      - name: Push changes to base branch (master or develop)
+        if: ${{ steps.update_readme.outcome == 'success' || steps.auto_version.outcome == 'success' }}
+        uses: ad-m/github-push-action@master
+        with:
+          branch: ${{ env.BASE_BRANCH }}

.github/workflows/pypi-publish.yml

@@ -15,18 +15,24 @@ jobs:
     environment:
       name: pypi
       url: https://pypi.org/p/finquant
+
     steps:
-      - uses: actions/checkout@v3
+      - name: Check out code
+        uses: actions/checkout@v3
+
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: '3.10'
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           python -m pip install .[cd]
+
       - name: Build package
         run: python setup.py sdist bdist_wheel
+
       - name: Publish package to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:

CONTRIBUTING.md

@@ -16,9 +16,24 @@ Before creating a new issue/bug report, check the list of existing [issues](http
 So you wish to fix bugs yourself, or contribute by adding a new feature. Awesome! Here are a few guidelines I would like you to respect.
 
 ### Create a fork
-First off, you should create a fork. Within your fork, create a new branch. Depending on what you want to do, choose one of the following prefixes for your branch:
-- bugfix/<name of your fix>: to be used for bug fixes
-- feature/<name of new feature>: to be used for adding a new feature
+First off, you should create a fork. Within your fork, create a new branch. Depending on what you want to do,
+choose one of the following prefixes for your branch name:
+- `bugfix/` followed by something like `<name of your fix>`: to be used for bug fixes
+- `feature/` followed by something like `<name of new feature>`: to be used for adding a new feature
+
+If you simply want to refactor the code base, or do other types of chores, use one of the following branch name prefixes:
+- `refactor/` followed by something like `<what you are refactoring>`
+- `chore/` followed by something like `<other type of contribution>`
+
+**NOTE**: It is _mandatory_ to use one of the above prefixes for your branch name. FinQuant uses GitHub workflows
+to automatically bump the version number when a PR is merged into `master` (or `develop`).
+The new version number depends on the source branch name of the merged PR.
+
+Example:
+. If you are working on a bugfix to fix a print statement of the portfolio properties,
+your branch name should be something like bugfix/print-statement-portfolio-properties.
+For the automated versioning to work, the branch name is required to start with `bugfix/` or one of the other
+above mentioned patterns.
 
 ### Commit your changes
 Make your changes to the code, and write sensible commit messages.
@@ -27,16 +42,22 @@ Make your changes to the code, and write sensible commit messages.
 In the root directory of your version of FinQuant, run `make test` and make sure all tests are passing.
 If applicable, add new tests in the `./tests/` directory. Tests should be written with `pytest`.
 
+Some few tests require you to have a [Quandl API key](https://docs.quandl.com/docs#section-authentication).
+If you do not have one locally, you can ignore the tests that are failing due to a missing Quandl API key.
+Once you open a PR, all tests are run by GitHub Actions with a pre-configured key.
+
 ### Documentation
-If applicable, please add docstrings to new functions/classes/modules. Follow example of existing docstrings. FinQuant uses `sphinx` to generate Documentation for [ReadTheDocs](https://finquant.readthedocs.io) automatically from docstrings.
+If applicable, please add docstrings to new functions/classes/modules.
+Follow example of existing docstrings. FinQuant uses `sphinx` to generate Documentation
+for [ReadTheDocs](https://finquant.readthedocs.io) automatically from docstrings.
 
 ### Style
-To keep everything consistent, please use [Black](https://github.com/psf/black) with default settings.
+Fortunately for you, you can ignore code formatting and fully focus on your contribution.
+FinQuant uses a GitHub workflow that is automatically triggered and runs [Black](https://github.com/psf/black) and
+[isort](https://pycqa.github.io/isort/) to format the code base for you.
 
 ### Create a Pull Request
-Create a new [Pull Request](https://github.com/fmilthaler/FinQuant/pulls). Describe what your changes are in the Pull Request. If your contribution fixes a bug, or adds a features listed under [issues](https://github.com/fmilthaler/FinQuant/issues) as "#12", please add "fixes #12" or "closes #12". 
-
-If you do not have a [Quandl API key](https://docs.quandl.com/docs#section-authentication) set as a secret in your fork, some of the tests are going to fail. 
-While you are working on your fork, you can ignore the Quandl specific tests that are failing. Once you are happy with your work,
-open a PR and use `master` as the target branch. GitHub Actions is set up to run the tests automatically for PRs, and the
-Quandl tests are then run with my secret API key.
+Create a new [Pull Request](https://github.com/fmilthaler/FinQuant/pulls).
+Describe what your changes are in the Pull Request.
+If your contribution fixes a bug, or adds a features listed under
+[issues](https://github.com/fmilthaler/FinQuant/issues) as "#12", please add "fixes #12" or "closes #12".

scripts/auto-commit.sh renamed to scripts/auto_commit.sh

@@ -1,16 +1,16 @@
 #!/bin/bash
 
-update_version_readme() {
+update_release_readme() {
 	local version_file="version"
 	local readme_md="$1"
 
-	# Read the current version from the "version" file
-	local current_version=$(grep -Eo 'version=([0-9]+\.){2}[0-9]+' "$version_file" | cut -d'=' -f2)
+	# Read the current release from the "version" file
+	local current_release=$(grep -Eo 'release=([0-9]+\.){2}[0-9]+' "$version_file" | cut -d'=' -f2)
 
 	update_file() {
 		local file=$1
-		sed -i "s/pypi-v[0-9]\+\.[0-9]\+\.[0-9]\+/pypi-v$current_version/" "$file"
-		echo "Version updated to $current_version in $file"
+		sed -i "s/pypi-v[0-9]\+\.[0-9]\+\.[0-9]\+/pypi-v$current_release/" "$file"
+		echo "Release updated to $current_release in $file"
 	}
 
 	# Update version in README.md
@@ -39,5 +39,5 @@ update_readme_tex() {
 
 # Update both readme files:
 echo "Updating README files:"
-update_version_readme "README.md"
+update_release_readme "README.md"
 update_readme_tex "README.tex.md"

scripts/auto-format.sh renamed to scripts/auto_format.sh

@@ -0,0 +1,133 @@
+import argparse
+import re
+
+# Define the version increments based on the change type (patch, minor, major)
+version_increments = {
+    "patch": "0.0.1",
+    "minor": "0.1.0",
+    "major": "1.0.0",
+}
+
+# Define the branch name prefixes for each change type
+branch_prefixes = {
+    "patch": ["chore/", "refactor/", "bugfix/"],
+    "minor": ["feature/"],
+    "major": None,
+}
+
+
+class VersionFileReadError(Exception):
+    pass
+
+
+# Function to increment the version based on the branch name pattern
+def increment_version(version, branch_name):
+    for change_type, prefixes in branch_prefixes.items():
+        prefixes = prefixes or []  # If None, set to an empty list
+        for prefix in prefixes:
+            if branch_name.startswith(prefix):
+                increment = version_increments[change_type]
+                return (
+                    increment_version_by(version, increment) if increment else version
+                )
+
+    return version
+
+
+# Function to increment the version by a given increment (e.g., "0.0.1" or "0.1.0" or "1.0.0")
+def increment_version_by(version, increment):
+    version_parts = version.split(".")
+    increment_parts = increment.split(".")
+
+    new_version_parts = []
+    for i in range(len(version_parts)):
+        if i < len(increment_parts):
+            new_version_parts.append(
+                str(int(version_parts[i]) + int(increment_parts[i]))
+            )
+        else:
+            new_version_parts.append("0")
+
+    # If increment is "0.1.0", reset the third digit to 0
+    if increment == "0.1.0" and len(version_parts) > 2:
+        new_version_parts[2] = "0"
+
+    # If increment is "1.0.0", reset the second and third digit to 0
+    if increment == "1.0.0" and len(version_parts) > 2:
+        new_version_parts[1] = "0"
+        new_version_parts[2] = "0"
+
+    return ".".join(new_version_parts)
+
+
+# Read the version from the file
+def read_version_from_file(filename):
+    with open(filename, "r") as file:
+        version_content = file.read()
+        version_match = re.search(r"version=(\d+\.\d+\.\d+)", version_content)
+
+        if version_match:
+            version = version_match.group(1)
+        else:
+            version = None
+
+        return version
+
+
+# Write the updated version back to the file
+def write_version_to_file(filename, version):
+    with open(filename, "r+") as file:
+        file_content = file.read()
+        updated_content = re.sub(
+            r"version=\d+\.\d+\.\d+", f"version={version}", file_content
+        )
+        # Always set the release number to match the updated version number
+        updated_content = re.sub(
+            r"release=\d+\.\d+\.\d+", f"release={version}", updated_content
+        )
+        file.seek(0)
+        file.write(updated_content)
+        file.truncate()
+
+
+# Function to parse command-line arguments
+def parse_args():
+    parser = argparse.ArgumentParser(description="Update version based on branch name.")
+    parser.add_argument("base_branch", help="Base branch name")
+    parser.add_argument("source_branch", help="Source branch name")
+    return parser.parse_args()
+
+
+# Main function
+def main():
+    args = parse_args()
+    base_branch_name = args.base_branch
+    source_branch_name = args.source_branch
+
+    file_path = "version"
+
+    if base_branch_name not in ["main", "develop"]:
+        raise ValueError("Base branch name must be 'main' or 'develop'.")
+
+    if source_branch_name is None:
+        raise ValueError("Source branch name must not be empty/None.")
+
+    current_version = read_version_from_file(file_path)
+    if current_version is None:
+        raise VersionFileReadError("Failed to read the current version from the file.")
+
+    updated_version = increment_version(current_version, source_branch_name)
+    print(f"Base branch: {base_branch_name}")
+    print(f"Source branch: {source_branch_name}")
+    print(f"Current version: {current_version}")
+    print(f"Updated version: {updated_version}")
+
+    if updated_version == current_version:
+        print("Version did not change.")
+    else:
+        write_version_to_file(file_path, updated_version)
+        print("Version updated in the file.")
+
+
+if __name__ == "__main__":
+    main()

scripts/update-readme.sh renamed to scripts/update_readme.sh

@@ -2,6 +2,7 @@
 # testing modules portfolio, optimisation, efficient_frontier #
 # all through the interfaces in Portfolio                     #
 ###############################################################
+
 import datetime
 import os
 import pathlib