Contributing Guide

Overview

Commits should follow this guide: https://chris.beams.io/posts/git-commit/

When opening a new issue, try to roughly follow the commit message format conventions above.

Be sure to include any related GitHub issue references in the commit message. See GFM syntax for referencing issues and commits.

Code style follows PEP8: https://www.python.org/dev/peps/pep-0008/

Please read our Developer Certificate of Origin. All contributions to this repository must be signed as described on that page. Your signature certifies that you wrote the patch or have the right to pass it on as an open-source patch. (Use -s option for git commit to do this automatically)

Community: https://vmwarecode.slack.com #vcd (channel)

Python

Verify python and pip installation with:

> python3 --version
Python 3.7.0

> pip3 --version
pip 18.0 from /usr/local/lib/python3.7/site-packages/pip (python 3.7)

Virtual Environments

A virtual environment is a project workspace (a folder/directory) where your project’s dependencies are isolated from the user/global space and from the dependencies of other projects. For example, if one project you’re working on requires Flask 1.0 and another project requires Flask 2.0, these projects have different dependencies, and without virtual environments, you can’t have both Flask 1.0 and 2.0. Having a virtual environment for each project will allow you to develop and test both of these projects on one machine.

The virtual environment program we will use is virtualenv, though there are others that do the same thing, such as pipenv, conda, venv, etc. The program virtualenvwrapper includes a lot of helpful shortcuts/functionality for managing your virtual environments, and using it is personal preference.

When no virtual environment is active, python packages install to user or global site-packages directory.

With a virtual environment active, python packages install to the virtual environment’s site-packages, and user/global site-packages are hidden from the interpreter

Install virtualenv

> pip3 install virtualenv

Virtual Environment Setup

More on virtual environments:

Project Setup

Git Setup

# Clone your forked repository to your local machine
> git clone https://github.com/USERNAME/container-service-extension

# Register the upstream remote repository as one of your project's known remote repositories
> git remote add upstream https://github.com/vmware/container-service-extension
origin	https://github.com/USERNAME/container-service-extension.git (fetch)
origin	https://github.com/USERNAME/container-service-extension.git (push)
upstream	https://github.com/vmware/container-service-extension.git (fetch)
upstream	https://github.com/vmware/container-service-extension.git (push)

Creating a Development Environment

CSE Usage and Testing

Configure vcd-cli to enable vcd cse ... commands

Edit ~/.vcd-cli/profiles.yaml to include this section:

extensions:
- container_service_extension.client.cse

If ~/.vcd-cli/profiles.yaml doesn’t exist, logging in to VCD via vcd-cli will create it

> vcd login IP ORGNAME USERNAME -iwp PASSWORD

Useful Commands

# see all commands with:
> vcd -h
> vcd cse -h
> cse -h

### Most 'vcd cse ...' commands require you to be logged in to VCD
# login as system administrator
> vcd login ip system USERNAME -iwp PASSWORD

# login as org user
> vcd login ip ORGNAME USERNAME -iwp PASSWORD

# use a target org while logged in as system administrator
> vcd org use ORGNAME

# see current login info
> vcd pwd

Set up VCD for Testing

In a VCD instance where you are system administrator. Assume default settings unless stated otherwise

Set up config.yaml

# get a sample config file to edit
cse sample > config.yaml

Testing Cheat Sheet

> cse install -c config.yaml
> cse version
> cse check -c config.yaml
> cse run -c config.yaml
> vcd login IP ORGNAME USERNAME -iwp PASSWORD
> vcd cse version
> vcd cse template list
> vcd cse system info
> vcd cse cluster create mycluster -n NETWORKNAME
> vcd cse cluster info mycluster
> vcd cse node create mycluster -n NETWORKNAME
> vcd cse node list mycluster
> vcd cse node info mycluster nodename
> vcd cse node delete mycluster nodename
> vcd cse cluster delete mycluster

Standard Git Workflow

Common Git commands:

### Harmless commands
# see current branch and state of changes
> git status

# see all local branches
> git branch

# see remote upstream's changes, but don't apply
> git fetch upstream

# switch local branches
> git checkout branchname

# view git commit log
> git log

### Commands with side effects
# signs the commit message to avoid annoying github bot
> git commit -s

# Adds changes to last commit and change commit message
> git commit --amend

# places all uncommitted changes into stash
> git stash

# lists all stashed changes
> git stash list

# applies the most recent stash and removes it from stash
> git stash pop

# without --rebase, applies pulled code on top of your current changes. With --rebase, applies the remote changes first, then applies your code changes on top of those.
> git pull --rebase

# allow user to modify commit history for latest 5 commits (squashing is very useful)
> git rebase -i HEAD~5

# Forces the remote origin branch to be the same as your local branch. Can be used to update an open pull request after using git rebase locally. Fairly safe to use since nothing should be forked from your remote origin
> git push origin branchname --force

Git resources: