The Framework-Assessment project has many moving parts, lots of auto-generated content, and a plethora of articulation points for customizations. With all of that, we know it can be daunting on how to actually develop this project. The goal of this guide is to provide just-enough information to get people going on developing to the standards required of the project.
It is written from the prospective that a potential contributor has zero (or next to zero) experience with one or more of the core software elements used to build the project. It links out to several sources that are more authoritative for those that desire to read more on the subject. Hopefully, with that point of view in mind, this document will be useful for people with all levels of skills in the development space to contribute to this project
For GitHub newbies, the first step you will probably need to start with is installing git itself. Git is a source control command line tool from the Linus Torvalds (the creator of Linux), and forms the base of GitHub's features. It will allow you to clone the Framework-Assessment repository to your local machine and make changes that can be eventually merged back into the project.
Once you have git installed for your Operating system, you will be ready to get started with GitHub. For this project, we make use of what is called the GitHub Flow for making changes/updates. To follow this flow, you will need to make a GitHub account.
GitHub Flow largely revolves around creating feature branches to "house" your proposed change. When you feel your proposed changes are ready, you will then open what is called a Pull Request that will be reviewed by the project maintainers (the FinOps++ Authors). The maintainers will provide feedback as needed, which could require making additional changes to your feature branch. Once feedback has been addressed and your proposed change has been approved by the maintainers, it will be merged into the default branch of the project. At which point you can delete you feature branch and then celebrate yourself becoming an published contributor to the Framework-Assessment project of FinOps++! 🥳
The finopspp CLI tool is a Python based tool that works for Python >= 3.13, it is recommended that you start off by creating a virtual environment (venv) as is discussed in https://docs.python.org/3/library/venv.html.
Once your venv is setup, activate it and run python -m pip install -e . from the same directory as this README. This command will pull in all required dependencies into the venv and then installs the script for you to use in your venv. It will also do this in what is called "editable" mode. Which will allow you to change packages and files (including yaml specifications) used by finopspp, and to directly see those changes reflected in the invocation of the tool. Be careful when doing this, so as not to break the core functionality needed to generate the assessment.
If you use VSCode, or would like to, you can follow the tutorial from https://code.visualstudio.com/docs/python/python-tutorial to get started with setting up this python project environment.
Important
The parts related to installing python and activating an existing venv should also work with pretty much any other IDE or text editor. So you are under no obligation to us VSCode if you have another coding tool like Vim, Emacs, PyCharm, Cursor, etc.
It is also recommended to read through https://realpython.com/python-pyproject-toml/ to get an overview of pyproject.toml based python projects. And to get a feel for the setup of this project in pyproject.toml used for finopspp.
The markdown files generated by the finopspp tool structured off of specialized Jinja2 templates that can be found under tools/templates. It is suggested that whatever text editor you use for development include support for the .j2 extension and jinja template syntax in general.
There are several composers used to aid in creating the different content provided by the Framework-Assessment project. It is quite possible, it could be argued, that of those, the most import is the one used to create the excel files used for the assessments. These live under tools/composers/excel and make use of the python version of xlsxwriter.
To fully develop for this, you will need to either have a properly licensed Microsoft Excel installed, or be on a Linux or Unix-like system that packages the free & opened sourced LibreOffice Calc. In this latter situation, you specifically will need to make sure that the libreoffice and make commands are installed. If they are, you can use the provided Makefile target make ods to convert existing excel files in the project to a natively supported LibreOffice format.
Note
You can directly open a .xlsx file in LibreOffice Calc, but some elements might be broken. It is strongly encouraged that you covert before using.