🚧 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 4.5 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

Addshore's avatar
Addshore committed
18
19
20
21
22
23
You need go 1.16+ installed.

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

```sh
Lens0021's avatar
Lens0021 committed
24
go install github.com/bwplotka/bingo@latest
Addshore's avatar
Addshore committed
25
26
```

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

30
Within the `~/go/src/gitlab.wikimedia.org/releng/cli` directory:
31

Addshore's avatar
Addshore committed
32
33
34
35
36
37
38
39
40
41
42
43
44
You can install allo tools used by this repository using bingo.

```sh
bingo get
```

You can then build a binary

```sh
make build
```

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

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

```sh
49
alias mwdev='~/go/src/gitlab.wikimedia.org/releng/cli/bin/mw'
50
51
52
53
54
55
56
57
58
59
60
61
```

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

63
### Packages & Directories
64

65
66
- `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
67
- `internal/config`: Interaction with the CLI configuration
68
- `internal/exec`: Wrapper for the main `exec` package, providing easy verbosity etc.
Addshore's avatar
Addshore committed
69
- `internal/gitlab`: Basic interaction with the Wikimedia Gitlab instance
70
71
- `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
72
- `internal/mwdd/files/embed`: Files that end up being extracted to disk for the dev environment under `~/mwcli/mwdd/default`.
Addshore's avatar
Addshore committed
73
- `internal/updater`: CLI tool updating.
Addshore's avatar
Addshore committed
74
- `internal/util`: A collection of quite well defined and restricted useful utility packages.
Addshore's avatar
Addshore committed
75
- `tests`: Integration tests that are run as part of CI.
76

77
78
79
80
81
### 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
82
83
84
- 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.
85
86
- This is a recursive solution.

87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
## CI & Integration tests

This repository has continious integration setup on Gitlab.
You can read more in the [CI README](./CI.md).

You can also choose to run the integration tests locally.

```sh
./tests/test-general-commands.sh
```

Or for the dev environment

```sh
./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.

Addshore's avatar
Addshore committed
109
## Releasing
Kosta Harlan's avatar
Kosta Harlan committed
110

Lens0021's avatar
Lens0021 committed
111
Releases are automatically built and published by Gitlab CI after pushing a tag.
Addshore's avatar
Addshore committed
112
113
114
115
116
117
118
119
120
121
122

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
123
5) You should now be able to run `mw update` to grab the latest release.