cli

README

MediaWiki CLI

This project contains a command-line interface primarily for interacting with 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/releng/cli.

Within the ~/go/src/gitlab.wikimedia.org/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/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/releng/cli/bin/mw'

Makefile commands

Many other Makefile commands exist that you might find useful:

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

Packages & Directories

• cmd: Contains the Cobra commands and deals with all CLI user interaction.
• internal/cmd: General Cobra command abstractions that may be useful in multiple places.
• internal/config: Interaction with the CLI configuration
• internal/exec: Wrapper for the main exec package, providing easy verbosity etc.
• internal/gitlab: Basic interaction with the Wikimedia Gitlab instance
• internal/mediawiki: Logic interacting with a MediaWiki installation directory on disk.
• internal/mwdd: Logic for the MediaWiki-docker-dev development environment.
• internal/mwdd/files/embed: Files that end up being extracted to disk for the dev environment under ~/mwcli/mwdd/default.
• internal/updater: CLI tool updating.
• internal/util: A collection of quite well defined and restricted useful utility packages.
• tests: Integration tests that are run as part of CI.
• tools: Various tools to make working with this repository easier.

cmd names

No naming structured is enforced in CI but a convention exists that should be followed.

• root.go exists as the overall CLI script.
• Major commands will have their own file in the cmd directory, named after the command. Example: mwdd.go.
• The lowest level commands can be included in their parent files. Example mwdd_mediawiki.go contains subcommands such as mwddMediawikiCmd.
• Complex sub commands can be split out into their own file.
• This is a recursive solution.
• Hidden commands can be created for debugging mwcli. These should be set as Hidden and be under the debug command.

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.
2. Tag & push the commit
3. Watch the pipeline run that is building, uploading and publishing the release.
4. Check that the release appear on the releases page
5. Publish up to date ref docs (see below)
6. You should now be able to run mw update to grab the latest release.

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!