Welcome, and thank you for deciding to invest some of your time in contributing to the Glasskube project! The goal of this document is to define some guidelines to streamline our contribution workflow.
There are many types of issues you can take on when contributing to the Glasskube project. We try our best to provide a wide array of open issues that vary in levels of complexity. From beginners to seasoned developers, everyone should be able to find something to work on.
- If you are new to the project, please check out the good first issue label.
- If you are ready to make a big impact on the project, check out the current milestone that is being worked on and filter the issues by
"help-wanted", these issues are the ones that will make it into the next official release. - If you are looking for something specific to work on, check out our open issues and filter against the available tags such as
component: cli,component: uicomponent: repo,documentation. - If you have an idea for a new feature, please open an issue, and we can discuss it.
- We are also happy to help you find something to work on. Just reach out to us.
- Join our Glasskube Discord Server.
- Introduce yourself in the
🎤|Introschannel or open an issue to let us know that you are interested in contributing.
- If you have a way of approaching an issue that is outside of the scope of the issues description, propose and discuss your solution in the issue itself.
- If you are unsure about something, don't hesitate to ask the community.
- Please
only work on oneissue at a time.- If you're unable to continue with an assigned task, inform us promptly.
- Ensure to
TESTyour feature contributions locally before requesting reviews.- Need assistance? Utilize the issue or
help-forumon Discord- While Generative AI can be useful, minimize its use for
direct team communication. We value concise, genuine exchanges over scripted messages.
Following these steps will ensure that your contributions are well-received, reviewed, and integrated effectively into Komiser's codebase.
- Assign yourself to the issue, if you are working on it (if you are not a member of the organization, please leave a comment on the issue and we will assign you to it.)
- Head over to the Glasskube GitHub repo and "fork it" into your own GitHub account.
- Clone your fork to your local machine, using the following command:
git clone git@github.com:USERNAME/FORKED-PROJECT.git- Create a new branch based-off `main` branch:
git checkout main
git checkout -b github_userName/XXXX-
Implement the changes or additions you intend to contribute. Whether it's bug fixes, new features, or enhancements, this is where you put your coding skills to use.
-
Once your changes are ready, you may then commit and push the changes from your working branch:
git commit -m "fix(xxxx-name_of_bug): nice commit description"
git push origin github_userName/XXXX- website
- cli
- ui
- package-operator
- If a commit spans across multiple scopes you could also concatenate them e.g. fix(ui,cli): nice commit message
- The commit message must start with a
lower caseletter
We require all commits in this repository to adhere to the following commit message format.
<type>: <description> (#<issue number>)
[optional body]
The following <type>s are available:
fix(bug fix)feat(includes new feature)docs(update to our documentation)build(update to the build config)perf(performance improvement)style(code style change without any other changes)refactor(code refactoring)chore(misc. routine tasks; e.g. dependency updates)
This format is based on Conventional Commits. Please refer to the Conventional Commits specification for more details.
If you plan on doing anything more than just a tiny quick fix, you’ll want to make sure you keep your fork up to date by tracking the original "upstream" repo that you forked.
Follow the steps given below to do so:
- Add the 'upstream' repo to list of remotes:
git remote add upstream https://github.com/glasskube/glasskube.git- Fetch upstream repo’s branches and latest commits:
git fetch upstream- Checkout to the `github_userName/XXXX` branch and merge the upstream:
git checkout github_userName/XXXX
git rebase upstream/mainNow, your local 'github_userName/XXXX' branch is up-to-date with everything modified upstream!
- Now it's time to create a pull request back to the upstream repository and follow the pull request template guidelines.
- Wait for a review and address any comments.
- As long as you are working on your PR, please mark it as a draft
- Please make sure that your PR is up-to-date with the latest changes in
main - Fill out the PR template
- Mention the issue that your PR is addressing (closes: #)
- Make sure that your PR passes all checks
- Keep pull requests small and focused, if you have multiple changes, please open multiple PRs
- Make sure to test your changes
- If you have multiple commits in your PR, that solve the same problem, please squash the commits
- Be respectful and constructive
- Assign yourself to the PR
- Check if all checks are passing
- Suggest changes instead of simply commenting on found issues
- If you are unsure about something, ask the author
- If you are not sure if the changes work, try them out
- Reach out to other reviewers if you are unsure about something
- If you are happy with the changes, approve the PR
- Merge the PR once it has all approvals and the checks are passing
Glasskube is developed using the Go programming language. The current version of Go being used is v1.22. It uses go modules for dependency management.
We use GNU Make and do not support other make flavors.
Once you've made your changes, you might want to build a binary of the glasskube CLI containing your changes to test them out. This can be done by running the following command at the root of the project:
make
This will create the glasskube and package-operator binary in the dist folder. You can execute the binary by running the following:
dist/glasskube
After you make more changes, simply run make again to recompile your changes.
In order to execute the glasskube binary locally, you can do this manually by creating a copy of it to your project directory.
However, there's an easy and preferred way for doing this by creating an alias using the following command:
alias <alias-name> = /path/to/glasskube/binary
This will make sure the alias-name is in sync with your glasskube binary. However, this is a temporary alias. If you'd like to create a permanent alias, you can read more about it here.
Note: Don't use alias-name as glasskube since the actual glasskube CLI tool installed locally will get in conflict with executable glasskube binary.
Install dependencies using the following command:
kubectl apply -k config/dependencies
tl;dr: Use minikube during development and run: make install webhook cert run
For development, we provide the following make targets:
make installinstalls the package-operator CRDs in the current cluster.make dependenciesinstalls the package-operator dependencies (Flux source-controller and helm-controller) in the current cluster.make webhookinstalls the package-operator webhook CRDs in the current cluster, including a patch to allow using the package-operator running on the local machine for the validating admission webhook (only works on minikube).make certruns the package-operator cert-manager locally to generate a self signed TLS certificate and patch the ValidatingWebhookConfiguration with the CA bundle. The TLS certificate is valid for 1 year, but is saved in a temporary directory, so it is recommended to run this task at least once everytime the machine is restarted.make setupis likemake install dependencies webhook certbut also creates the default Glasskube package repository in the cluster. This is probably what you want to use to get started quickly.make runruns the package-operator locally.make docker-buildbuilds a docker image for the package-operator.make deployapplies the full package-operator manifest (excluding dependencies) in the current cluster.
The package-operator ships with a ValidatingAdmissionWebhook. While it is not mandatory to use it during development, we do recommend that you do. Just follow these steps:
make installcreates the package-operator CRDs in your cluster.make webhookcreates an "ExternalName" service in your cluster that points to your host machine. This only works if you use minikube, if you want to use kind instead, take a look at this issue.- With the webhook configuration in place, you have to generate a TLS certificate locally and patch the webhook configuration with the CA bundle by running
make cert. - Alternatively, you can just run
make setup, which includes all of the above. - Run the operator using your preferred environment, or
make run.
When changing the manifests, it is recommended to deploy the package-operator in a minikube cluster. To achieve this, you will have to do three things:
- Point your local docker CLI to the minikube docker daemon:
minikube docker-envfor more info - Build the docker image:
make docker-build - Deploy the operator using the locally built image:
make deploy
We have a minimal set of dependencies that need to be installed to work on the web UI locally. Install them with make web.
This will download and install the glasskube theme, Bootstrap and htmx.
After this you are ready to go by running the serve command: go run cmd/glasskube/main.go serve.
We are aware that the developer experience for the web part could be improved, e.g. by introducing hot reload.
Sometimes it's necessary to develop and test new features and their different edge cases, and the official package repository does not include these cases yet.
In this case, you can host your own repository locally and change the package repository URL in the code.
- Clone the packages repository.
- Make your changes locally and host it, e.g. with caddy:
caddy file-server --root . --listen :9684from the root directory of the packages project. - In
internal/repo/interface.go, change the repository URL tohttp://localhost:9684/packages. - Make sure to restart your applications (operator, CLI, UI), such that the local repository is being used everywhere.
We do not have a command line option yet to change the repository URL, so for now the code change is necessary.
Also note that some of the information in the repository is redundant by design, to reduce the amount of queries against the repo.
For example, the index.yaml contains a latestVersion for each package, but the latestVersion is also defined in each package index file.
Please make sure to have consistent and valid state in your local repo.
It's crucial to acknowledge the significance of various types of testing. Alongside conducting unit tests for your contributed code, it's imperative to locally build Glasskube and
test it within a Kubernetes cluster. ☸️
In case you don't have access to a remote Kubernetes cluster, set up a local testing environment using Minikube. This guide will help you set up a single node cluster in no time, which will be more than enough for you Glasskube testing needs.
Install dependencies and build
npm ci
make allUnit tests for the project can be executed by running:
make test
This command will run all the unit tests, will try to detect race conditions, and will generate a test coverage report.
Before making a PR, we recommend contributors to run a lint check on their code by running:
make lint
Some linting errors can be automatically fixed by running:
make lint-fix
