element-hq / element-hq/synapse
Unclear documentation text concerning the `--exists-ok` option (`register_new_matrix_user`)
- 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
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