Improve Montage local development setup documentation (OAuth configuration and WSL recommendation) #411
Description
Problem
While attempting to set up Montage for local development, the current documentation was not entirely clear and led to several setup issues. In particular, the OAuth configuration and environment setup steps need more detailed guidance.
Additionally, running the backend directly on Windows can lead to dependency and environment issues. Using WSL (Windows Subsystem for Linux) provides a smoother and more consistent setup experience, but this is not currently mentioned in the documentation.
Observed Issues
-
OAuth configuration with MediaWiki is not clearly explained.
-
The documentation does not clearly explain how to create an OAuth consumer.
-
Enabling the "owner-only" option during OAuth consumer creation can lead to the error:
mwoauth.errors.OAuthException: Consumer is owner-only (E010)
-
-
The callback URL and required grants for the OAuth consumer are not clearly documented.
-
The development environment setup could be improved for Windows users.
Suggested Improvements
Add a more detailed Local Development Setup Guide that includes:
1. Recommended Environment
- Recommend running the backend inside WSL (Windows Subsystem for Linux) for Windows users instead of running it directly on Windows.
- Provide brief steps to install and use WSL for development.
2. OAuth Consumer Setup
Provide a step-by-step guide for creating an OAuth consumer on Meta Wikimedia, including:
- Application name
- Callback URL
- Required grants
- Project selection
3. Example Configuration
Provide an example config.dev.yaml snippet for local development.
4. Troubleshooting
Add a troubleshooting section covering common issues such as:
Invalid consumerConsumer is owner-only (E010)- OAuth callback issues
Expected Outcome
Improving the documentation would make the onboarding process for new contributors significantly easier and reduce time spent troubleshooting OAuth and environment setup issues.