local-it/vikunja-api
0
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
vikunja-api/docs/content/doc/development/mage.md

193 lines
5.8 KiB
Markdown
Raw Normal View History

Switch to mage (#651) Add comment about magefile compile Switch make to mage commands in drone Fix misspell Update docs Add general release command Add reprepro command Make sure the filename contains the proper version Add deb package building Add zip command Preserve file permissions when copying files Fix release:os-package Make sure to not create checksums of directories Cleanup Only compress what upx is able to compress Add check command Add release:os-package command Add copy command Add comments Add compress step Move releasing binaries to a more general function and add ones of linux + darwin Add release:windows command Add release:dir command Add namespaces for commands Reorder Add command to run all checks at once Add goconst-check Add gosec-check Add static-check Add gocyclo-check Add ineffasign-check Add misspell-check Add command to check for swagger docs regeneration Add comments Add command to generate swagger docs Reorder Add check for installing golint before running it Add fmt check command Add fmt command Use runAndStreamOutput everywhere Add aliases and comments Add todo Reorder Add test coverage command Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/651
2020-09-03 17:13:19 +02:00
---
date: "2019-02-12:00:00+02:00"
title: "Magefile"
draft: false
type: "doc"
menu:
sidebar:
parent: "development"
---
# Mage
Vikunja uses [Mage](https://magefile.org/) to script common development tasks and even releasing.
Mage is a pure go solution which allows for greater flexibility and things like better paralelization.
This document explains what taks are available and what they do.
Add toc to docs
2020-09-03 17:34:44 +02:00
{{< table_of_contents >}}
Switch to mage (#651) Add comment about magefile compile Switch make to mage commands in drone Fix misspell Update docs Add general release command Add reprepro command Make sure the filename contains the proper version Add deb package building Add zip command Preserve file permissions when copying files Fix release:os-package Make sure to not create checksums of directories Cleanup Only compress what upx is able to compress Add check command Add release:os-package command Add copy command Add comments Add compress step Move releasing binaries to a more general function and add ones of linux + darwin Add release:windows command Add release:dir command Add namespaces for commands Reorder Add command to run all checks at once Add goconst-check Add gosec-check Add static-check Add gocyclo-check Add ineffasign-check Add misspell-check Add command to check for swagger docs regeneration Add comments Add command to generate swagger docs Reorder Add check for installing golint before running it Add fmt check command Add fmt command Use runAndStreamOutput everywhere Add aliases and comments Add todo Reorder Add test coverage command Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/651
2020-09-03 17:13:19 +02:00
## Installation
To use mage, you'll need to install the mage cli.
To install it, run the following command:
```
go install github.com/magefile/mage
```
## Categories
There are multiple categories of subcommands in the magefile:
* `build`: Contains commands to build a single binary
* `check`: Contains commands to statically check the source code
* `release`: Contains commands to release Vikunja with everything that's required
* `test`: Contains commands to run all kinds of tests
Add mage command to create a new migration
2020-09-04 10:15:33 +02:00
* `dev`: Contains commands to run development tasks
Switch to mage (#651) Add comment about magefile compile Switch make to mage commands in drone Fix misspell Update docs Add general release command Add reprepro command Make sure the filename contains the proper version Add deb package building Add zip command Preserve file permissions when copying files Fix release:os-package Make sure to not create checksums of directories Cleanup Only compress what upx is able to compress Add check command Add release:os-package command Add copy command Add comments Add compress step Move releasing binaries to a more general function and add ones of linux + darwin Add release:windows command Add release:dir command Add namespaces for commands Reorder Add command to run all checks at once Add goconst-check Add gosec-check Add static-check Add gocyclo-check Add ineffasign-check Add misspell-check Add command to check for swagger docs regeneration Add comments Add command to generate swagger docs Reorder Add check for installing golint before running it Add fmt check command Add fmt command Use runAndStreamOutput everywhere Add aliases and comments Add todo Reorder Add test coverage command Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/651
2020-09-03 17:13:19 +02:00
* `misc`: Commands which do not belong in either of the other categories
## CI
These tasks are automatically run in our CI every time someone pushes to master or you update a pull request:
* `mage check:lint`
* `mage check:fmt`
* `mage check:ineffassign`
* `mage check:misspell`
* `mage check:goconst`
* `mage build:generate`
* `mage build:build`
## Build
### Build Vikunja
{{< highlight bash >}}
mage build:build
{{< /highlight >}}
Builds a `vikunja`-binary in the root directory of the repo for the platform it is run on.
### Statically compile all templates into the binary
{{< highlight bash >}}
mage build:generate
{{< /highlight >}}
This generates static code with all templates, meaning no template need to be referenced at runtime.
### clean
{{< highlight bash >}}
mage build:clean
{{< /highlight >}}
Cleans all build, executable and bindata files
## Check
All check sub-commands exit with a status code of 1 if the check fails.
Various code-checks are available:
* `mage check:all`: Runs fmt-check, lint, got-swag, misspell-check, ineffasign-check, gocyclo-check, static-check, gosec-check, goconst-check all in parallel
* `mage check:fmt`: Checks if the code is properly formatted with go fmt
* `mage check:go-sec`: Checks the source code for potential security issues by scanning the Go AST using the [gosec tool](https://github.com/securego/gosec)
* `mage check:goconst`: Checks for repeated strings that could be replaced by a constant using [goconst](https://github.com/jgautheron/goconst/)
* `mage check:gocyclo`: Checks for the cyclomatic complexity of the source code using [gocyclo](https://github.com/fzipp/gocyclo)
* `mage check:got-swag`: Checks if the swagger docs need to be re-generated from the code annotations
* `mage check:ineffassign`: Checks the source code for ineffectual assigns using [ineffassign](https://github.com/gordonklaus/ineffassign)
* `mage check:lint`: Runs golint on all packages
* `mage check:misspell`: Checks the source code for misspellings
* `mage check:static`: Statically analyzes the source code about a range of different problems using [staticcheck](https://staticcheck.io/docs/)
## Release
### Build Releases
{{< highlight bash >}}
mage release
{{< /highlight >}}
Builds binaries for all platforms and zips them with a copy of the `templates/` folder.
All built zip files are stored into `dist/zips/`. Binaries are stored in `dist/binaries/`,
binaries bundled with `templates` are stored in `dist/releases/`.
All cross-platform binaries built using this series of commands are built with the help of
[xgo](https://github.com/techknowlogick/xgo). The mage command will automatically install the
binary to be able to use it.
`mage release:release` is a shortcut to execute `mage release:dirs release:windows release:linux release:darwin release:copy release:check release:os-package release:zip`.
* `mage release:dirs` creates all directories needed
* `mage release:windows`/`release:linux`/`release:darwin` execute xgo to build for their respective platforms
* `mage release:copy` bundles binaries with a copy of the `LICENSE` and sample config files to then be zipped
* `mage release:check` creates sha256 checksums for each binary which will be included in the zip file
* `mage release:os-package` bundles a binary with the `sha256` checksum file, a sample `config.yml` and a copy of the license in a folder for each architecture
* `mage release:compress` compresses all build binaries with `upx` to save space
* `mage release:zip` paclages a zip file for the files created by `release:os-package`
Use nfpm to build deb, rpm and apk packages (#689) Cleanup Update docs for deb Add building os packages to drone Add apk packages Replace version and binlocation strings in nfpm config Make nfpm config replacable Fix nfpm config Add nfpm config go mod tidy Add nfpm mage target Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/689 Co-Authored-By: konrad <konrad@kola-entertainments.de> Co-Committed-By: konrad <konrad@kola-entertainments.de>
2020-10-18 13:41:27 +02:00
### Build os packages
Switch to mage (#651) Add comment about magefile compile Switch make to mage commands in drone Fix misspell Update docs Add general release command Add reprepro command Make sure the filename contains the proper version Add deb package building Add zip command Preserve file permissions when copying files Fix release:os-package Make sure to not create checksums of directories Cleanup Only compress what upx is able to compress Add check command Add release:os-package command Add copy command Add comments Add compress step Move releasing binaries to a more general function and add ones of linux + darwin Add release:windows command Add release:dir command Add namespaces for commands Reorder Add command to run all checks at once Add goconst-check Add gosec-check Add static-check Add gocyclo-check Add ineffasign-check Add misspell-check Add command to check for swagger docs regeneration Add comments Add command to generate swagger docs Reorder Add check for installing golint before running it Add fmt check command Add fmt command Use runAndStreamOutput everywhere Add aliases and comments Add todo Reorder Add test coverage command Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/651
2020-09-03 17:13:19 +02:00
{{< highlight bash >}}
Use nfpm to build deb, rpm and apk packages (#689) Cleanup Update docs for deb Add building os packages to drone Add apk packages Replace version and binlocation strings in nfpm config Make nfpm config replacable Fix nfpm config Add nfpm config go mod tidy Add nfpm mage target Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/689 Co-Authored-By: konrad <konrad@kola-entertainments.de> Co-Committed-By: konrad <konrad@kola-entertainments.de>
2020-10-18 13:41:27 +02:00
mage release:packages
Switch to mage (#651) Add comment about magefile compile Switch make to mage commands in drone Fix misspell Update docs Add general release command Add reprepro command Make sure the filename contains the proper version Add deb package building Add zip command Preserve file permissions when copying files Fix release:os-package Make sure to not create checksums of directories Cleanup Only compress what upx is able to compress Add check command Add release:os-package command Add copy command Add comments Add compress step Move releasing binaries to a more general function and add ones of linux + darwin Add release:windows command Add release:dir command Add namespaces for commands Reorder Add command to run all checks at once Add goconst-check Add gosec-check Add static-check Add gocyclo-check Add ineffasign-check Add misspell-check Add command to check for swagger docs regeneration Add comments Add command to generate swagger docs Reorder Add check for installing golint before running it Add fmt check command Add fmt command Use runAndStreamOutput everywhere Add aliases and comments Add todo Reorder Add test coverage command Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/651
2020-09-03 17:13:19 +02:00
{{< /highlight >}}
Use nfpm to build deb, rpm and apk packages (#689) Cleanup Update docs for deb Add building os packages to drone Add apk packages Replace version and binlocation strings in nfpm config Make nfpm config replacable Fix nfpm config Add nfpm config go mod tidy Add nfpm mage target Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/689 Co-Authored-By: konrad <konrad@kola-entertainments.de> Co-Committed-By: konrad <konrad@kola-entertainments.de>
2020-10-18 13:41:27 +02:00
Will build `.deb`, `.rpm` and `.apk` packages to `dist/os-packages`.
Switch to mage (#651) Add comment about magefile compile Switch make to mage commands in drone Fix misspell Update docs Add general release command Add reprepro command Make sure the filename contains the proper version Add deb package building Add zip command Preserve file permissions when copying files Fix release:os-package Make sure to not create checksums of directories Cleanup Only compress what upx is able to compress Add check command Add release:os-package command Add copy command Add comments Add compress step Move releasing binaries to a more general function and add ones of linux + darwin Add release:windows command Add release:dir command Add namespaces for commands Reorder Add command to run all checks at once Add goconst-check Add gosec-check Add static-check Add gocyclo-check Add ineffasign-check Add misspell-check Add command to check for swagger docs regeneration Add comments Add command to generate swagger docs Reorder Add check for installing golint before running it Add fmt check command Add fmt command Use runAndStreamOutput everywhere Add aliases and comments Add todo Reorder Add test coverage command Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/651
2020-09-03 17:13:19 +02:00
### Make a debian repo
{{< highlight bash >}}
mage release:reprepro
{{< /highlight >}}
Takes an already built debian package and creates a debian repo structure around it.
Used to be run inside a [docker container](https://git.kolaente.de/konrad/reprepro-docker) in the CI process when releasing.
## Test
### unit
{{< highlight bash >}}
mage test:unit
{{< /highlight >}}
Runs all tests except integration tests.
### coverage
{{< highlight bash >}}
mage test:coverage
{{< /highlight >}}
Runs all tests except integration tests and generates a `coverage.html` file to inspect the code coverage.
### integration
{{< highlight bash >}}
mage test:integration
{{< /highlight >}}
Runs all integration tests.
Add mage command to create a new migration
2020-09-04 10:15:33 +02:00
## Dev
### Create a new migration
{{< highlight bash >}}
mage dev:create-migration
{{< /highlight >}}
Creates a new migration with the current date.
Will ask for the name of the struct you want to create a migration for.
Switch to mage (#651) Add comment about magefile compile Switch make to mage commands in drone Fix misspell Update docs Add general release command Add reprepro command Make sure the filename contains the proper version Add deb package building Add zip command Preserve file permissions when copying files Fix release:os-package Make sure to not create checksums of directories Cleanup Only compress what upx is able to compress Add check command Add release:os-package command Add copy command Add comments Add compress step Move releasing binaries to a more general function and add ones of linux + darwin Add release:windows command Add release:dir command Add namespaces for commands Reorder Add command to run all checks at once Add goconst-check Add gosec-check Add static-check Add gocyclo-check Add ineffasign-check Add misspell-check Add command to check for swagger docs regeneration Add comments Add command to generate swagger docs Reorder Add check for installing golint before running it Add fmt check command Add fmt command Use runAndStreamOutput everywhere Add aliases and comments Add todo Reorder Add test coverage command Co-authored-by: kolaente <k@knt.li> Reviewed-on: https://kolaente.dev/vikunja/api/pulls/651
2020-09-03 17:13:19 +02:00
## Misc
### Format the code
{{< highlight bash >}}
mage fmt
{{< /highlight >}}
Formats all source code using `go fmt`.
### Generate swagger definitions from code comments
{{< highlight bash >}}
mage do-the-swag
{{< /highlight >}}
Generates swagger definitions from the comment annotations in the code.
Reference in a new issue Copy permalink