Contributing
This document is a work in progress. We will be documenting the inner workings of the ORY GitHub ecosystem and project structures in here. If you feel there is something missing or should be added, please open an issue in ory/docs or contact us on the forum or chat.
#
Releasing SoftwareTo release a project, run the following bash command in the root of the project you would like to release. The first argument can be one of:
patch
bumpsv1.2.3
tov1.2.4
(does not work for pre-releases such asv1.2.3-beta.1
)minor
bumpsv1.2.3
tov1.3.0
(does not work for pre-releases such asv1.2.3-beta.1
)major
bumpsv1.2.3
tov2.0.0
(does not work for pre-releases such asv1.2.3-beta.1
)- Any semver-valid version, for example
v1.2.3-beta.1
#
Defining Release ConfigFor the scripts to work, the project must be located in a directory structure
that reflects the GitHub organisation and repository name, for example:
path/to/ory/hydra
.
#
GoreleaserWe use goreleaser.
The listed configuration options should be included in every .goreleaser.yml
config. Make sure you set env vars and go mod download
and run e.g. packr2 and
other tools first:
Tag -alpha.1
and other pre-release tags as pre-release on GitHub:
Name snapshot releases -next
:
If you create a new goreleaser config, you may also want to create the following empty GitHub repositories:
Build and publish on Docker. You need to create a repository on Docker Hub first!
If you add Scoop (Homebrew for Windows) you must also create
a GitHub repository under the ory
org named scoop-$PROJECT_NAME
(e.g.
scoop-hydra
).
If you add Homebrew you must also create a GitHub repository
under the ory
org named homebrew-$PROJECT_NAME
(e.g. homebrew-hydra
).
We use the following replacements:
#
Update install scriptWhen you have finalized changes to the .goreleaser.yml
, run:
#
CircleCIDefine CI Environment Variables:
- Make sure you set
GITHUB_TOKEN
in the project's CI config. - Make sure you set
MAILCHIMP_API_KEY
in the project's CI config. - Make sure you set
DOCKER_USER
in the project's CI config. - Make sure you set
DOCKER_TOKEN
in the project's CI config.
In the project's CircleCI config (.circleci/config.yml
), use the following
workflow (please use an appropriate $VERSION
):
#
CIWe use our own CircleCI Orbs:
#
ory/nancyEnables nancy vulnerability scanning for the repository.
#
Toolchain#
Checking for vulnerabilities#
NodeJSThis is done automatically by GitHub
#
Go#
Pinning indirect go module dependencies.Sometimes a project has an indirect dependency (another dependency requires that
dependency) which does not pass, for example, nancy
vulnerability scanning.
Because it's not possible to pin this dependency to a specific version, we need
to explicitly require it. But because it's not directly required by our code, it
will be pruned when using go mod tidy
. To prevent that, create a file which
imports the dependency without use:
You would do the same if the project uses dev tools such as packr2
,
goimports
, goreturns
, swagutil
, ... as part of e.g. the Makefile or other
scripts.
#
Development#
DBAL gobuffalo/pop#
Table NamesPlease define custom table names for all table structs. Keep in mind that
TableName()
must be a value receiver, not a pointer receiver, for slices
[]Model
to work properly: