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 Software#

To 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 bumps v1.2.3 to v1.2.4 (does not work for pre-releases such as v1.2.3-beta.1)
  • minor bumps v1.2.3 to v1.3.0 (does not work for pre-releases such as v1.2.3-beta.1)
  • major bumps v1.2.3 to v2.0.0 (does not work for pre-releases such as v1.2.3-beta.1)
  • Any semver-valid version, for example v1.2.3-beta.1
release_as=v1.2.3
bash <(curl -s https://raw.githubusercontent.com/ory/meta/master/scripts/release.sh) $release_as

Defining Release Config#

For 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.

Goreleaser#

We 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:

.goreleaser.yml
env:
- GO111MODULE=on
before:
hooks:
- go mod download
# - go install github.com/gobuffalo/packr/v2/packr2
# - packr2

Tag -alpha.1 and other pre-release tags as pre-release on GitHub:

release:
prerelease: auto

Name snapshot releases -next:

snapshot:
name_template: '{{ .Tag }}-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!

# Build dockerfiles
dockers:
- dockerfile: Dockerfile
binaries:
- $PROJECT_NAME
image_templates:
- 'oryd/$PROJECT_NAME:v{{ .Major }}'
- 'oryd/$PROJECT_NAME:v{{ .Major }}.{{ .Minor }}'
- 'oryd/$PROJECT_NAME:v{{ .Major }}.{{ .Minor }}.{{ .Patch }}'
- 'oryd/$PROJECT_NAME:latest'

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).

scoop:
bucket:
owner: ory
name: scoop-$PROJECT_NAME
homepage: https://www.ory.sh
commit_author:
name: aeneasr
email: aeneas@ory.sh

If you add Homebrew you must also create a GitHub repository under the ory org named homebrew-$PROJECT_NAME (e.g. homebrew-hydra).

brews:
- github:
owner: ory
name: homebrew-$PROJECT_NAME
ids:
- <<REPLACE-WITH-ARCHIVE-ID>>
homepage: https://www.ory.sh
commit_author:
name: aeneasr
email: aeneas@ory.sh

We use the following replacements:

archives:
- replacements:
darwin: macOS
386: 32-bit
amd64: 64-bit
format_overrides:
- goos: windows
format: zip

Update install script#

When you have finalized changes to the .goreleaser.yml, run:

$ GO111MODULES=off go get -u github.com/goreleaser/godownloader
$ godownloader .goreleaser.yml --repo=$(basename $(dirname $(pwd)))/$(basename $(pwd)) > ./install.sh

CircleCI#

Define 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):

orbs:
goreleaser: ory/goreleaser@0.1.7
slack: circleci/slack@3.4.2
workflows:
my-workflow:
jobs:
- goreleaser/test:
filters:
tags:
only: /.*/
- goreleaser/release:
requires:
- goreleaser/test
filters:
branches:
ignore: /.*/
tags:
only: /.*/
- goreleaser/newsletter-draft:
chimp-list: f605a41b53
chimp-segment: 6478605
requires:
- goreleaser/release
filters:
tags:
only: /.*/
- slack/approval-notification:
message: Pending approval
channel: release-automation
requires:
- goreleaser/newsletter-draft
filters:
tags:
only: /.*/
- newsletter-approval:
type: approval
requires:
- goreleaser/newsletter-draft
filters:
tags:
only: /.*/
- goreleaser/newsletter-send:
chimp-list: f605a41b53
requires:
- newsletter-approval
filters:
tags:
only: /.*/

CI#

We use our own CircleCI Orbs:

ory/nancy#

Enables nancy vulnerability scanning for the repository.

orbs:
nancy: ory/nancy@0.0.9
workflows:
test:
jobs:
- nancy/test:
filters:
tags:
only: /.*/

Toolchain#

Checking for vulnerabilities#

NodeJS#

This is done automatically by GitHub

Go#

# Outside of a go module-enabled project:
$ go get -u github.com/sonatype-nexus-community/nancy
# Inside your go module-enabled project:
$ go mod list -m all | nancy

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:

// +build go_mod_indirect_pins
package main
import _ "github.com/my/dependency"

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 Names#

Please 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:

-func (m *Model) TableName(ctx context.Context) string {
+func (m Model) TableName(ctx context.Context) string {
return "foo"
}
Last updated on by aeneasr