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, or are already a seasoned contributor, check out our unassigned
"help wanted"issues. - 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 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:
# replace USERNAME with your GitHub username
git clone [email protected]:USERNAME/glasskube.git- Please use a feature branch based on `main` for your changes. This allows easier synchronization with the main repository:
git switch main
git switch -c your-awesome-new-feature-
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: nice commit description"
git push origin your-awesome-new-feature- Create a Pull Request following our pull request template to request a code-review.
Glasskube uses a workflow based on GitHubs "Squash & Merge" feature. We therefore require all pull request titles to adher to the syntax specified by Conventional Commits. We do not restrict the format of your commit messages, however we do encourage using the Conventional Commits syntax as well.
In case you've never heard of Conventional Commits, here's a brief summary:
- Every message consists of a header and optional body and footer (for PR titles, there is no body or footer).
- The header consists of a type, an optional scope in parentheses and a description.
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
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)
For more details, please refer to the Conventional Commits specification.
Glasskube has an active community of contributors, with new PRs being created and merged almost every day.
This means that the upstream repository might change during the time between you creating your fork and your PR being accepted.
The easiest way to incorporate these changes into your fork is by synchronizing your fork via the GitHub UI and then merging your forks (now up to date) main branch into your feature branch:
Visit your fork in a browser, open the "Sync fork" dropdown and press the big "Update branch" button. Then open your local project in a terminal and run
git fetch --all
git merge origin/mainNow, your feature branch is up-to-date with everything modified upstream!
Please avoid rebasing or force-pushing your branch, because this prevents our code-review team from tracking changes since their last review.
- 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
- 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 add it to the list of repositories in your cluster.
- 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. - Run
glasskube repo add local http://localhost:9684to add this repository with the namelocal. - Make sure to restart your applications (operator, CLI, UI), such that the local repository is being used everywhere.
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.
Also please be aware of the package repo cache: When changing something in the repo, you might want to restart the applications again (otherwise you might have to wait up to 5 minutes).
There is no option yet to override the cache time, but you could locally change it in internal/repo/client/clientset.go:NewClientset.
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
