🚧 This instance is under construction; expect occasional downtime. Runners available in /repos. Questions? Ask in #wikimedia-gitlab on libera.chat, or under GitLab on Phabricator.

README.md 3.72 KB
Newer Older
Kosta Harlan's avatar
Kosta Harlan committed
1
2
# MediaWiki CLI

Kosta Harlan's avatar
Kosta Harlan committed
3
This project contains a command-line interface primarily for interacting with a MediaWiki development environment modeled after [mediawiki-docker-dev](https://www.mediawiki.org/wiki/MediaWiki-Docker-Dev)
Kosta Harlan's avatar
Kosta Harlan committed
4

Addshore's avatar
Addshore committed
5
6
Take a look at the user facing docs https://www.mediawiki.org/wiki/Cli

Addshore's avatar
Addshore committed
7
8
9
10
11
12
13
## Support

- Code Repository: [releng/cli on gitlab.wikimedia.org](https://gitlab.wikimedia.org/releng/cli)
- Documentation: [Cli page on mediawiki.org](https://www.mediawiki.org/wiki/Cli)
- Phabricator: [#mwcli on phabricator.wikimedia.org](https://phabricator.wikimedia.org/project/view/5331/)
- IRC: `#mediawiki` on [Libera.​Chat](https://libera.chat/)

14
15
## Contributing

Addshore's avatar
Addshore committed
16
17
### Repo / Code setup

Kosta Harlan's avatar
Kosta Harlan committed
18
Clone this repository to your `$GOPATH` (probably `~/go`), so it would be at
19
`~/go/src/gitlab.wikimedia.org/releng/cli`.
20

21
Within the `~/go/src/gitlab.wikimedia.org/releng/cli` directory:
22

23
Run `make` to build a binary to `~/go/src/gitlab.wikimedia.org/releng/cli/bin/mw`.
24

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

```sh
28
alias mwdev='~/go/src/gitlab.wikimedia.org/releng/cli/bin/mw'
29
30
31
32
33
34
35
36
37
38
39
40
```

### 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/
41

42
### Packages & Directories
43

44
45
- `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.
Addshore's avatar
Addshore committed
46
- `internal/config`: Interaction with the CLI configuration
47
48
49
- `internal/docker`: Logic interacting with the mediawiki-docker dev environment.
- `internal/env`: Logic interacting with a `.env` file.
- `internal/exec`: Wrapper for the main `exec` package, providing easy verbosity etc.
Addshore's avatar
Addshore committed
50
- `internal/gitlab`: Basic interaction with the Wikimedia Gitlab instance
51
52
- `internal/mediawiki`: Logic interacting with a MediaWiki installation directory on disk.
- `internal/mwdd`: Logic for the MediaWiki-docker-dev development environment.
Addshore's avatar
Addshore committed
53
- `internal/updater`: CLI tool updating.
54
- `static`: Files that end up being built into the binary.
Addshore's avatar
Addshore committed
55
- `tests`: Integration tests that are run as part of CI.
56

57
58
59
60
61
### 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.
Addshore's avatar
Addshore committed
62
63
64
- 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.
65
66
- This is a recursive solution.

Addshore's avatar
Addshore committed
67
## Releasing
Kosta Harlan's avatar
Kosta Harlan committed
68

Addshore's avatar
Addshore committed
69
70
71
72
73
74
75
76
77
78
79
80
Releases are automaticaly built and published by Gitlab CI after pushing a tag.

Tags should follow [semver](https://semver.org/) 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](https://gitlab.wikimedia.org/releng/cli/-/compare/v0.2.0...main?from_project_id=16) 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](https://gitlab.wikimedia.org/releng/cli/-/pipelines) that is building, uploading and publishing the release.
4) Check that the release appear [on the releases page](https://gitlab.wikimedia.org/releng/cli/-/releases)
Kosta Harlan's avatar
Kosta Harlan committed
81
5) You should now be able to run `mw update` to grab the latest release.