element-hq / element-hq/synapse

Unclear documentation text concerning the `--exists-ok` option (`register_new_matrix_user`)

Open Beginner friendly
#20,112 0 comments 0 reactions 0 assignees View on GitHub
A-Docs
Dominant language
Python
Stars
4.6k
Forks
600
Avg merge
5d 22h
Merged PRs (30d)
51

Description

### Description

For the `register_new_matrix_user` command, there is an option, documented as below:

```
--exists-ok Do not fail if user already exists.
```

The wording is unclear as to whether this means that the command will update the user's profile to match the rest of the invoked command, or if it will simply exit and do nothing if the user already exists.

From reading some of the source code, it seems to be the behavior of the program that it does the latter.

This documentation may exist elsewhere aside from just in this command.

The flag was added in #17304

### Steps to reproduce

To verify the documentation I am referring to, `register_new_matrix_user --help`

To verify the behavior of the command, I read the source code, which you could do as well. Alternatively, you could test it. One idea is to run these two commands on a test synapse server and see if the user ends up as an admin:

```
register_new_matrix_user -u test-user --password-file password.txt --no-admin
register_new_matrix_user -u test-user --password-file password.txt --admin --exists-ok
```

Under my understanding, the 2nd command _does not_ change the user into an admin, and as far as I know this is by design. My complaint is that the documentation is not clear that this is the case.

Here's the source code in question:

https://github.com/element-hq/synapse/blob/c0357de4eda2f32919d89b4cffa306d68562c022/synapse/_scripts/register_new_matrix_user.py#L102-L109

### Homeserver

localhost

### Synapse Version

{"server_version":"1.156.0}

### Installation Method

Other (please mention below)

### Database

A singlular PostgreSQL. I have not ported from SQLite, nor restored from a backup.

### Workers

Single process

### Platform

This is running in an Artix Linux VM (Artix Linux is an Arch Linux variety). I installed the package using pacman. Here's the package info:

```
$ pacman -Qi matrix-synapse
Name : matrix-synapse
Version : 1.156.0-1
Description : Matrix reference homeserver
Architecture : x86_64
```

### Configuration

None of those, and nothing else as far as I am aware.

### Relevant log output

```shell
N/A
```

### Anything else that would be useful to know?

_No response_

Contributor guide

Open the contributing guide

Research direction

Start with synapse/_scripts/register_new_matrix_user.py at the referenced source lines and search for other documentation of --exists-ok. Run register_new_matrix_user --help and, if needed, the two test commands on a test Synapse server to confirm the existing user is unchanged. Done means the option text clearly states that an existing user is left unchanged and the wording is consistent wherever it appears.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.