# Contributing to KubeVirt.io

[![Build Status](https://prow.ci.kubevirt.io/badge.svg?jobs=push-kubevirt.github.io-main-build-and-push-to-gh-pages)](https://prow.ci.kubevirt.io/?repo=kubevirt%2Fkubevirt.github.io&type=postsubmit&job=push-kubevirt.github.io-main-build-and-push-to-gh-pages)

The [kubevirt.io](https://kubevirt.io) website is a [Jekyll](https://jekyllrb.com/) 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 ...

```bash
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  ...

```bash
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...

```bash
git remote add upstream http/ssh url
```

And then you should see something like...

```bash
$ 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 ...

```bash
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 ...

```bash
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 ...

```bash
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 ...

```bash
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 ...

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


#### Work

[Here is our guidelines for content contribution](GUIDELINES.md).

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](https://github.com/kubevirt/kubevirt.github.io/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fwebsite) 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
```bash
$ make build_img
```

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

```bash
$ export CONTAINER_ENGINE=docker
$ export BUILD_ENGINE=docker
```

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

```bash
$ export SELINUX_ENABLED=True
```

2) Validate page rendering
```bash
make run
```
Open your web browser to http://0.0.0.0:4000

3) Test all hyperlinks
```bash
make check_links
```

4) Test spelling
```bash
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
```bash
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!
```bash
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
```bash
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

```console
$ 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:

1. Ensure that you have added yourself to our [adopters file](https://github.com/kubevirt/kubevirt/blob/main/ADOPTERS.md) in the kubevirt/kubevirt repo. There are three [adopter types](https://github.com/kubevirt/kubevirt/blob/main/ADOPTERS.md#adopter-types) and each list is alphabetical. The PR needs to be merged before you can open the PR to add your logo here.
1. Open a branch of this repo and add your logo in `assets/images/adopters` in either png or svg format.
1. 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.
1. (Optional but good practice) [Test your changes](https://github.com/kubevirt/kubevirt.github.io?tab=readme-ov-file#test-work) by building a local copy of the website.
1. 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`.
1. 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](https://calendar.google.com/calendar/u/0/embed?src=kubevirt@cncf.io)

## Privacy

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