Contributing to KubeVirt.io

The kubevirt.io website is a Jekyll driven site hosted by GitHub Pages.

Contributions to the KubeVirt website are very much welcomed! Please reach out with ideas for new content or issues with existing content!

Getting Started

Git semantics

A semi standard process is followed to move code from development to production.

The basic process is ...

Fork -> Clone -> Branch -> Commit -> Push -> Pull Request -> Approve -> Merge

Fork

Create a forked copy of the repository to your account by pressing the Fork button at the top of the repository page. This should be the only time a fork needs to be created as long as the fork is properly maintained by performing branch sync and rebase with upstream periodically.

Clone

To clone the forked repository locally, browse to your fork at https://www.github.com/*github_name*/kubevirt.github.io. Click the Code button. Select a clone method and copy the url to clipboard. Open a terminal window and ...

git clone *clipboard paste url*

Remotes

By default the local git repo will have a remote alias called origin that points to your fork in GitHub. KubeVirt repositories have many contributors so work needs to be done periodically to synchronize local and origin branches with upstream branches. To enable this work flow on your local clone, add a new remote to the repository. By convention, this remote is named upstream.

To add an additional remote perform the following command...

git remote add upstream http/ssh url

And then you should see something like...

$ git remote -v
origin  git@github.com:mazzystr/kubevirt.github.io.git (fetch)
origin  git@github.com:mazzystr/kubevirt.github.io.git (push)
upstream    git@github.com:kubevirt/kubevirt.github.io.git (fetch)
upstream    git@github.com:kubevirt/kubevirt.github.io.git (push)

To sync the main branch from the upstream repository, perform the following ...

git checkout main; git fetch upstream; git reset --hard upstream/main; git push origin main -f

Note main branch is purely cosmetic for this repo. Merges to main ARE NOT ACCEPTED.

All work must be branched from main branch. Perform the following to sync from upstream ...

git checkout main; git fetch upstream; git reset --hard upstream/main; git push origin main -f

Feature branch

Even though changes from a local main branch are accepted it is inadvisable, can cause confusion and possibly data loss. Please use feature branches branched from main by running the following ...

git checkout main; git fetch upstream; git reset --hard upstream/main; git push origin main -f; git branch feat_branch; git checkout feat_branch; git push --set-upstream origin feat_branch

Rebase

Periodically a feature branch will need to be rebased as the local and origin fall behind upstream. Perform the following to rebase ...

git checkout main; git fetch upstream; git reset --hard upstream/main; git push origin main -f; git checkout feat_branch; git rebase origin/main; git push -f

There is always a strong possibility for merge conflicts. Proceed with caution in resolving. Each conflict must be hand edited. Perform the following to resolve each conflict ...

# Modify and save the filename
git add filename; git rebase --continue

Work

Here is our guidelines for content contribution.

Each section of the site is broken out into their respective folders.

./pages : website
./blogs : blog posts
./docs : documentation.
./videos : videos

All site images are located under ./assets/images. Please do not edit these images.

Markdown for blog posts are located under ./posts. Please follow the existing filename scheme.

Images related to blog entries get placed under ./assets/images/BLOG_POST_TITLE. The BLOG_POST_TITLE should match the name of the markdown file created under /_posts.

If you are a UI/UX developer, the structure and layout of the website would greatly benefit from your attention. Feel free to browse website issues or contribute other ideas.

Test work

The Makefile at the base of this repository provides editors the ability to locally run the same tests CI uses to validate changes. This saves time over waiting for online CI resources to spin up just to find out a pull request has a problem that prevents merge.

1) Build the test image locally

$ make build_img

NOTE If you use docker you may need to set CONTAINER_ENGINE and BUILD_ENGINE:

$ export CONTAINER_ENGINE=docker
$ export BUILD_ENGINE=docker

NOTE If you are in an SELinux enabled OS you need to set SELINUX_ENABLED:

$ export SELINUX_ENABLED=True

2) Validate page rendering

make run

Open your web browser to http://0.0.0.0:4000

3) Test all hyperlinks

make check_links

4) Test spelling

make check_spelling

If you discover a flagged spelling error that you believe is not a mistake, feel free to add the offending word to the dictionary file located at GitHub repo kubevirt/project-infra/images/yaspeller/.yaspeller.json. Try to keep the dictionary file well ordered and employ regular expressions to handle common patterns.

5) Lint Markdown

make check_lint

If you discover a markdown error that you believe should be ignored, you should look to add it to the markdownlint.yaml configuration file. If there is a file that needs to have linting skipped, it can be added to the .markdownlintignore configuration file.

Make sure all tests pass before committing!

Submitting your code

1) Commit your code and sign your commits!

git commit -s -m "The commit message" file1 file 2 file3 ...

Signature verification on commits are required! No exceptions!

You will see the following in the transaction log

git log
commit hashbrowns (HEAD -> feat_branch, upstream/main, origin/main, main)
Author: KubeVirt contributer <kubevirt_contributer@kubevirt.io>
Date:   Mon Jan 01 00:00:00 2021 -0700

<your commit message>

Signed-off-by: <your configured git identity>

2) Browse to https://www.github.com/*you*/kubevirt.github.io

3) Often you will see a Compare & Pull Request button ... Click on that

4) Ensure your base branch is main, your compare branch is feat_branch, and the file diff's are correct.

5) Create a nice subject and body for the pull request. Be sure to tag related issues, people of interest, and click the "Create pull request" button.

Maintainers will automatically be notified a pull request has been created and will give further instruction on getting contribution merged.

Makefile Help

$ make help

Makefile for website jekyll application

Usage:
  make <target>

Env Variables:
  CONTAINER_ENGINE  Set container engine, [*podman*, docker]
  BUILD_ENGINE      Set build engine, [*podman*, buildah, docker]
  SELINUX_ENABLED   Enable SELinux on containers, [*False*, True]

Targets:
  help                   Show help
  build_img              Build image localhost/kubevirt-kubevirt.github.io
  check_links            Check external, internal links and links/selectors to userguide on website content
  check_lint             Check markdown linting
  check_spelling         Check spelling on content
  run                    Run site. App available @ http://0.0.0.0:4000
  status                 Container status
  stop                   Stop site

Environment Variables

CONTAINER_ENGINE: Some of us use docker. Some of us use podman (default: podman).
BUILD_ENGINE: Some of us use docker. Some of us use podman (default: podman)
SELINUX_ENABLED: Some of us run SELinux enabled. Set to True to enable container mount labelling

Targets:

build_img: Use this target to build an image packed with Jekyll, casperjs, yaspeller and HTMLProofer.
check_links: HTMLProofer is used to check any links to external websites as well as any cross-page links. Casperjs is used to dissect user-guide urls containing markdown selectors and ensure they exist.
check_lint: uses markdownlint to check for markdown linting. Can be configured via the .markdownlint.yaml and .markdownlintignore configuration files.
check_spelling: yaspeller is used to check spelling. Feel free to update to the dictionary file as needed (kubevirt/project-infra/images/yaspeller/.yaspeller.json).
status: Basically ${BUILD_ENGINE} ps for an easy way to see what's running.
stop: Stop container and app

Adopters

If you are a KubeVirt adopter and want to see your logo on the website:

Ensure that you have added yourself to our adopters file in the kubevirt/kubevirt repo. There are three adopter types and each list is alphabetical. The PR needs to be merged before you can open the PR to add your logo here.
Open a branch of this repo and add your logo in assets/images/adopters in either png or svg format.
In the same branch, run the _data/adopters.py script from within the _data folder. This script checks our ADOPTERS file in kubevirt/kubevirt and automatically updates the associated adopters file in our website code with your logo.
(Optional but good practice) Test your changes by building a local copy of the website.
Open a PR to merge your branch in the repo. There should be two files changed: a new file for your logo and the edited adopters.yml file in _data.
Feel free to ping your reviewers if they have not responded in a week or two.

Getting Help

Mailing list: https://groups.google.com/g/kubevirt-dev
Slack: https://kubernetes.slack.com/messages/virtualization
Twitter: https://twitter.com/kubevirt

Developer

Github project: https://github.com/kubevirt
Community meetings: Google Calendar

Privacy

Check our privacy policy at: https://kubevirt.io/privacy/

kubevirt / kubevirt.github.io

readme