-
-
Notifications
You must be signed in to change notification settings - Fork 5.4k
docs: simplify and clarify installation instructions #10674
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's a good idea to add a Contributing guide, but this one is too generic. Also, the relevant content is already in the readme.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, you're replacing the installation instructions for users by installation instructions for contributors. Instead, you should clarify that the installation instructions are for users, and leave the instructions unchanged.
Hi @fzaninotto 👋
Thanks again for the feedback!
I’ve updated the CONTRIBUTING.md file based on your comments. I also wanted to explain the intention behind the changes a bit more clearly:
I’ve been collecting feedback and documentation-related issues — especially those raised by newcomers and students — and noticed recurring problems mentioned in issues like #10662 and #10634. These issues highlight areas where users are encountering setup errors or confusion, particularly during local development and installation.
Since some of these issues (e.g., errors in the current setup video) might take time to resolve or recreate, I thought adding a quick and updated section to the documentation would be helpful in the meantime. The goal is to make the onboarding process smoother for contributors and new users alike, without interfering with the core user installation instructions.
I understand your concern but the solution you propose doesn't work for us:
- You're using generic content in Contributing
- You're including a super specific gotcha in contributing that has nothing to do with first time contributors
- You're degrading the README for non-contributors.
Uh oh!
There was an error while loading. Please reload this page.
Problem
The current installation instructions in the documentation rely solely on npm install react-admin, which can cause issues or confusion, especially for beginners. Several users (including students) reported difficulties setting up the project this way. The current method is also missing a quick-start guide for local development.
Solution
This PR updates the documentation (README.md) and adds a CONTRIBUTING.md file with a simplified installation workflow:
git clone
yarn install
cd react-admin
yarn run-simple
This method is easier to follow, faster to execute, and resolves issues some users encountered with npm-based installs.
How To Test
Clone the repo using the new instructions.
Run yarn install, then cd react-admin and yarn run-simple.
Confirm the app starts successfully and mirrors expected behavior.
Additional Checks
masterfor a bugfix or a documentation fix, ornextfor a featureAlso, please make sure to read the contributing guidelines.
Closes #10673