Building, Testing, and Contributing¶
Testing latest commits¶
You can download the latest artifacts from the master branch from link. On macOS and Linux you can
brew unlink ddev && brew install drud/ddev/ddev --HEAD --fetch-HEAD to get the latest commit of ddev, even if it's not yet in a release. If you are using linux/WSL2, you will also likely need to install build-essential with the following command:
sudo apt install -y build-essential.
To download the latest version, you can visit the master-build workflow and choose the latest item (or the one that matches a commit you want to test). You'll see the artifacts for each OS there on the bottom of the page.
And of course you can just see the latest build in action by visiting ddev on gitpod.
Testing a PR¶
Each build of a PR has artifacts created in github, so you can click the details of the PR Build test, choose the PR you want to work with, and download the artifacts you need there.
After you download and unzip the appropriate binary, you can place it in your $PATH. The easiest way to do this if you're using homebrew is
brew unlink ddev and then
unzip ddev.zip && chmod +x ddev && mv ddev /usr/local/bin/ddev.
You can verify that the replacement worked via
ddev -v. The output should be something like
ddev version v1.19.1-42-g5334d3c1 (instead of the regular
ddev version v1.19.1).
(On macOS Big Sur these downloaded binaries are not signed, so you will want to
xattr -r -d com.apple.quarantine /path/to/ddev in order to use them. The binaries on the master branch and the final binaries in any release are signed, of course.)
You do not typically have to install anything else other than the downloaded binary; when you run it it will access any docker images that it needs.
After you're done, you can remove the downloaded binary and
brew link ddev.
Open in Gitpod¶
Gitpod.io provides a quick preconfigured ddev experience in the browser, so you can test your PR (or someone else's) easily and without setting up an environment. In any PR you can use the URL
https://gitpod.io/#https://github.com/drud/ddev/pulls/<YOURPR> to open that PR and build it in Gitpod.
If you want to run a web project in there, you can just check it out into
/workspace/<yourproject> and use it as usual. The things you're familiar with work as expected, except that
ddev-router does not run, and
A dummy project for gitpod is provided by default in /workspace/d9simple. You can just
ddev poweroff and use your own.
Making changes to ddev images¶
If you need to make a change to one of the ddev images, you can make the change, but then it has to be built with a specific tag, and the tag has to be updated in
pkg/versionconstants/versionconstants.go. So for example, make a change to containers/ddev-webserver/Dockerfile, then built it:
pkg/versionconstants/versionconstants.go to set
var WebTag = "20210424_fix_dockerfile" and
ddev version should show you that you are using the correct webtag, and
ddev start will show it.
It's easiest to do this using gitpod (see above) because gitpod already has
docker buildx all set up for you and the built ddev is in the $PATH.
Pull Requests and PR Preparation¶
When preparing your pull request, please use a branch name like "2020_
Docker Image changes¶
If you make changes to a docker image (like ddev-webserver), it won't have any effect unless you:
- Push an image with a specific tag by going to the image directory (like containers/ddev-webserver) by just doing
make container VERSION=<branchname>in the containers/ddev-webserver directory.
- Multi-arch images require you to have a buildx builder, so
docker buildx create --name ddev-builder-multi --use
- You can't push until you
- Push a container to hub.docker.com. Push with the tag that matches your branch. Pushing to
<yourorg>/ddev-webserverrepo is easy to accomplish with
make push DOCKER_ORG=<yourorg> VERSION=<branchname>in the container directory. You might have to use other techniques to push to another repo.
WebTagthat relate to the docker image you pushed.
Local builds and pushes¶
buildx successfully you have to have the
buildx docker plugin which is in many environments by default.
To build multi-platform images you must
docker buildx create --use as a one-time initialization.
If you just want to work locally and do a quick build for your own architecture, you can:
make mariadb_10.3 VERSION=<version>etc.
To push manually:
If you're pushing to a repo other than the one wired into the Makefile (like
Pushes using GitHub Actions¶
To manually push using GitHub Actions,
For most images¶
- Visit Actions->Push Tagged Image
- Click "Run workflow" in the blue band near the top.
- Choose the branch, usually
masterand then the image to be pushed,
ddev-dbserver, etc. Also you can use
allto build and push all of them. Include a tag for the pushed image and GitHub will do all the work.
- Visit Actions->Push Tagged db Image
- Click "Run workflow" in the blue band near the top.
- Choose the branch, usually
master. Include a tag for the pushed image and GitHub will do all the work.
- You'll want both your fork/branch and the upstream as remotes in git, so that tags can be determined. For example, the upstream git remote can be
https://github.com/drud/ddevand your fork's remote can be
email@example.com:<yourgithubuser>/ddev. Without the upstream, git may not know about tags that it needs for tests to work.
- To run tests, you'll want
~/tmpto be allowed in docker. This is not normally an issue as the home directory is available by default in most docker providers.
Build the project with
make and your resulting executable will end up in
.gotmp/bin/linux_arm64/ddev (for Linux) or
.gotmp/bin/windows_amd64/ddev.exe (for Windows) or
.gotmp/bin/darwin_arm64/ddev (for macOS).
Build/test/check static analysis with
Normal test invocation is just
make test. Run a single test with an invocation like
go test -v -run TestDevAddSites ./pkg/... or
make testpkg TESTARGS="-run TestDevAddSites". The easiest way to run tests is from inside the excellent golang IDE Goland. Just click the arrowhead to the left of the test name.
To see which DDEV commands the tests are executing, set the environment variable DDEV_DEBUG=true.
Use GOTEST_SHORT=true to run just one CMS in each test, or GOTEST_SHORT=
GOTEST_SHORT=5 make testpkg TESTARGS="-run TestDdevFullSiteSetup" will run only
TestDdevFullSiteSetup only against TYPO3.
To run a test (in the cmd package) against a individually compiled ddev binary set the DDEV_BINARY_FULLPATH environment variable, for example
DDEV_BINARY_FULLPATH=$PWD/.gotmp/bin/linux_amd64/ddev make testcmd. The easiest way to run tests is using GoLand (or vscode) with their built-in test runners and debuggers. You can step through a specific test; you can stop at the point before the failure and experiment with the site that the test has set up.
Anybody can view the CircleCI automated tests, and they usually show up any problems that are not OS-specific. Just click through on the testing section of the PR to see them.
The Buildkite automated tests require special access, which we typically grant to any PR contributor that asks for it.
Docker image development¶
The Docker images that DDEV uses are included in the containers/ directory:
- containers/ddev-php-base: The base build for ddev-webserver.
- containers/ddev-webserver: Provides the web servers (the "web" container).
- containers/ddev-dbserver: Provides the "db" container.
- containers/ddev-router: The router image
When changes are made to an image, they have to be temporarily pushed to a tag that is preferably the same as the branch name of the PR, and the tag updated in
pkg/versionconstants/versionconstants.go. Just ask if you need a container pushed to support a PR.
Pull Request Pro Tips¶
- Fork the repository and clone it locally. Connect your local to the original ‘upstream’ repository by adding it as a remote. - Pull in changes from ‘upstream’ often so that you stay up to date so that when you submit your pull request, merge conflicts - will be less likely. See more detailed instructions here.
- Create a branch for your edits.
- Be clear about what problem is occurring and how someone can recreate that problem or why your feature will help. Then be equally as clear about the steps you took to make your changes.
- It’s best to test. Run your changes against any existing tests if they exist and create new ones when needed. Whether tests exist or not, make sure your changes don’t break the existing project.
Open Pull Requests¶
Once you’ve opened a pull request, a discussion will start around your proposed changes. Other contributors and users may chime in, but ultimately the decision is made by the maintainer(s). You may be asked to make some changes to your pull request. If so, add more commits to your branch and push them – they’ll automatically go into the existing pull request.
If your pull request is merged – great! If it is not, no sweat, it may not be what the project maintainer had in mind, or they were already working on it. This happens, so our recommendation is to take any feedback you’ve received and go forth and pull request again – or create your own open source project.
Adapted from GitHub Guides
Unless explicitly stated, we follow all coding guidelines from the Go community. While some of these standards may seem arbitrary, they somehow seem to result in a solid, consistent codebase.
It is possible that the code base does not currently comply with these guidelines. We are not looking for a massive PR that fixes this since that goes against the spirit of the guidelines. All new contributions should make a best effort to clean up and make the code base better than they left it. Obviously, apply your best judgment. Remember, the goal here is to make the code base easier for humans to navigate and understand. Always keep that in mind when nudging others to comply.
make staticrequired to ensure that your code can pass the required static analysis tests.
- All code should be formatted with
- All code should pass the default levels of
- All code should follow the guidelines covered in Effective Go and Go Code Review Comments.
- Comment the code. Tell us the why, the history and the context.
- Document all declarations and methods, even private ones. Declare expectations, caveats and anything else that may be important. If a type gets exported, having the comments already there will ensure it's ready.
- Variable name length should be proportional to its context and no longer.
noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo. In practice, short methods will have short variable names and globals will have longer names.
- No underscores in package names. If you need a compound name, step back, and re-examine why you need a compound name. If you still think you need a compound name, lose the underscore.
- All tests should run with
go testand outside tooling should not be required. No, we don't need another unit testing framework. Assertion packages are acceptable if they provide real incremental value.
- Even though we call these "rules" above, they are actually just guidelines. Since you've read all the rules, you now know that.
If you are having trouble getting into the mood of idiomatic Go, we recommend reading through Effective Go. The Go Blog is also a great resource. Drinking the kool-aid is a lot easier than going thirsty.