3.4 KiB

Raw Blame History

Contributing to democratic-csi

Development Environment Setup

This project uses a hybrid development approach with devcontainers for IDE configuration and Vagrant for system-level testing.

Prerequisites

Before you begin, ensure you have the following installed:

Visual Studio Code
Docker
Vagrant
Virtualization Provider:
- For Intel/AMD Machines: VirtualBox
- For Apple Silicon: Qemu (brew install qemu vagrant and vagrant plugin install vagrant-qemu)

Development Workflow

1. Local Development with Devcontainers

Devcontainers provide a consistent development environment with:

Configured VSCode extensions
Necessary development tools
Integrated development experience

To use the devcontainer:

Open the project in VSCode
Install the "Dev Containers" extension
Click "Reopen in Container" when prompted
Start coding with pre-configured environment

[!Note] For iSCSI it's mandatory to use the Vagrant VM, due to the need of a kernel driver. However for other tests the container is probably enough. It's possible to run the hack/run.sh as explained below in the devcontainer and see if it's possible, before spinning up a full VM.

2. System Testing with Vagrant

Vagrant provides a full virtual machine environment for:

System-level testing
Running code with kernel dependencies
Simulating production-like environments

Workflow:

# Navigate to project directory
cd ~/democratic-csi

# Start the Vagrant VM
vagrant up

# Connect to the VM
vagrant ssh

# Inside the VM, navigate to the project
cd ~/democratic-csi

# Run project tests, the config.yaml can be any from the examples folders
# just configured for your own environment.
# You can also create a file `dev/secrets.env` that has `export VARIABLE=VALUE`
# and reference those in your `config.yaml`
./hack/run.sh -c ./hack/config.yaml

Keeping Files in Sync

Use these methods to keep your local files synchronized with the Vagrant VM:

Manual Sync

# Sync files from local to Vagrant VM
vagrant rsync

Continuous Sync

# Automatically sync files as they change
vagrant rsync-auto

Best Practices

Use devcontainer for day-to-day development and coding
Use Vagrant for comprehensive system testing
Always run vagrant rsync before running tests in the VM
Commit and push changes frequently
If encountering issues, try:
1. Recreating the devcontainer
2. Reprovisioning the Vagrant VM with vagrant reload --provision or vagrant destroy -f && vagrant up

Troubleshooting

Devcontainer Issues

Ensure Docker is running
Rebuild the container if extensions fail to load
Check VSCode Dev Containers extension logs

Vagrant Issues

Verify virtualization is enabled in your BIOS
Ensure you have the latest Vagrant and virtualization provider
For Apple Silicon, use Parallels or Lima

Contribution Guidelines

Create a new branch for your feature targetting next
Write clear, concise commit messages
Include coverage for tests of csi-sanity for new functionality
Run tests in Vagrant VM
Submit a pull request with a clear description of changes

Contact

For any questions or issues, please open an issue on the project repository.

3.4 KiB Raw Blame History