cli

README

MediaWiki CLI

This project contains a command-line interface for MediaWiki and Wikimedia developers.

It includes a MediaWiki development environment modeled after mediawiki-docker-dev.

Take a look at the user facing docs https://www.mediawiki.org/wiki/Cli

Support

• Code Repository: releng/cli on gitlab.wikimedia.org
• Documentation: Cli page on mediawiki.org
• Phabricator: #mwcli on phabricator.wikimedia.org
• IRC: #mediawiki on Libera.​Chat

Contributing

Repo / Code setup

You need go 1.16+ installed.

This repository uses the bingo tool. You can install it with:

go install github.com/bwplotka/bingo@latest

Clone this repository to your $GOPATH (probably ~/go), so it would be at ~/go/src/gitlab.wikimedia.org/repos/releng/cli.

Within the ~/go/src/gitlab.wikimedia.org/repos/releng/cli directory:

You can install all tools used by this repository using bingo.

bingo get

You can then build a binary

make build

Which you will find at ~/go/src/gitlab.wikimedia.org/repos/releng/cli/bin/mw.

We recommend that you create a development alias for this binary, and run make after you make changes to the codebase.

alias mwdev='~/go/src/gitlab.wikimedia.org/repos/releng/cli/bin/mw'

Makefile commands

Many other Makefile commands exist that you might find useful:

• make build: Builds a new binary
• make release: Builds multiple release binaries to _release
• make test: Run unit tests
• make lint: Run basic linting
• make fix: Run basic lint fixes
• make vet: Run go vet
• make staticcheck: Run https://staticcheck.io/

Packages & Directories

• cmd: Creationand execution of the top level mw cobra CLI command.
• internal/cli: High level things used across the CLI.
• internal/util: Independant packages that do not bind the the CLI.
• internal/cmd: Packages for commands that make up part of the CLI, binding to cobra.
• internal/<command name>: Packages for commands that should not bind to cobra.
• tests: Integration tests that are run as part of CI.
• tools: Various tools to make working with this repository easier.

CI & Integration tests

This repository has continious integration setup on Gitlab. You can read more in the CI README.

You can also choose to run the integration tests locally.

./tests/test-general-commands.sh

Or for the dev environment

./tests/test-docker-general.sh
./tests/test-docker-mw-all-dbs.sh
./tests/test-docker-mw-mysql-cycle.sh

These tests should clean up after themselves. If you run into issues you might find ./tests/destroy.sh useful.

Releasing

Releases are automatically built and published by Gitlab CI after pushing a tag.

Tags should follow semver and release notes should be written prior to tagging.

Process

1. Add release notes for the release into CHANGELOG.md
   • You can use a compare link such as this to see what has changed and what needs release notes.
   • Notes should be under a fresh new header of the format ## v0.2.1 so that the release process can extract the notes correctly. These are displayed to users as they update.
2. Tag the commit for release
   • The format should be vx.x.x
   • The v prefix is needed for the release CI to run for the tag
3. Watch the pipeline run that is building, uploading and publishing the release.
4. Check that the release appear on the releases page
5. You should now be able to run mw update to grab the latest release.
6. Publish up to date ref docs (see below)
7. Update the version in the installation docs code snippets

Docs

Docs for mediawiki.org can be automatically generated from this repository.

Note: You will need pandoc installed. https://pandoc.org/

make docs

If you also want to publish them, you'll need something like this:

make user="someUser" password="somePassword" docs-publish

You can use a bot password for this https://mediawiki.org/wiki/Special:BotPasswords

In the future this would be done by CI!