Fix : README Add Missing Setup Instructions, Troubleshooting, and Contribution Workflow Add Missing Setup Instructions, Troubleshooting, and Contribution Workflow #121
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
the
area/docs
saurabhraghuvanshii
requested changes
Jan 3, 2026
| make setup | ||
|
|
||
| # Run the project locally | ||
| make run |
Member
There was a problem hiding this comment.
Suggested change
| make run | |
| make site |
| |---------|-------------| | ||
| | `make help` | Display all available make commands | | ||
| | `make setup` | Install all required dependencies | | ||
| | `make run` | Start the local development server | |
Member
There was a problem hiding this comment.
Suggested change
| | `make run` | Start the local development server | | |
| | `make site` | Start the local development server | |
Comment on lines
+176
to
+211
| ### 🐛 Troubleshooting | ||
|
|
||
| #### Port Already in Use | ||
|
|
||
| If port 8000 is already in use: | ||
|
|
||
| ```bash | ||
| # Kill the process using port 8000 | ||
| lsof -ti:8000 | xargs kill -9 | ||
|
|
||
| # Or use a different port | ||
| npm start -- -p 3000 | ||
| ``` | ||
|
|
||
| #### Cache Issues | ||
|
|
||
| If you encounter build issues: | ||
|
|
||
| ```bash | ||
| npm run clean | ||
| npm install | ||
| npm start | ||
| ``` | ||
|
|
||
| #### Node Version Issues | ||
|
|
||
| Ensure you're using the correct Node.js version: | ||
|
|
||
| ```bash | ||
| # Check Node version | ||
| node --version | ||
|
|
||
| # If using nvm, switch to recommended version | ||
| nvm use | ||
| ``` | ||
|
|
Member
There was a problem hiding this comment.
Suggested change
| ### 🐛 Troubleshooting | |
| #### Port Already in Use | |
| If port 8000 is already in use: | |
| ```bash | |
| # Kill the process using port 8000 | |
| lsof -ti:8000 | xargs kill -9 | |
| # Or use a different port | |
| npm start -- -p 3000 | |
| ``` | |
| #### Cache Issues | |
| If you encounter build issues: | |
| ```bash | |
| npm run clean | |
| npm install | |
| npm start | |
| ``` | |
| #### Node Version Issues | |
| Ensure you're using the correct Node.js version: | |
| ```bash | |
| # Check Node version | |
| node --version | |
| # If using nvm, switch to recommended version | |
| nvm use | |
| ``` |
|
|
||
| 1. **Start the Application** - Open http://localhost:8000 in your browser | ||
| 2. **Click on Canvas** - Click multiple points to create your polygon shape | ||
| 3. **Close the Shape** - Double-click or click "Close Shape" button |
Member
There was a problem hiding this comment.
Suggested change
| 3. **Close the Shape** - Double-click or click "Close Shape" button | |
| 3. **Close the Shape** - Enter or ESC |
Comment on lines
-152
to
-168
| <!--### Community | ||
| See an <a href="https://layer5.io/community/handbook/repository-overview">overview of repositories</a> and projects by tech stack in the <a href="https://meshery.io/community#handbook/">Community Handbook</a>. | ||
| ## See Meshery in Action | ||
| - [DockerCon 2020](https://docker.events.cube365.net/docker/dockercon/content/Videos/63TCCNpzDC7Xxnm8b) | ([video](https://www.youtube.com/watch?v=5BrbbKZOctw&list=PL3A-A6hPO2IN_HSU0pSfijBboiHggs5mC&index=4&t=0s), [deck](https://calcotestudios.com/talks/decks/slides-dockercon-2020-service-meshing-with-docker-desktop-and-webassembly.html)) | ||
| - [Deploying Linkerd with Meshery](https://youtu.be/MXQV-i-Hkf8) | ||
| - [KubeCon EU 2019](https://kccnceu19.sched.com/event/MPf7/service-meshes-at-what-cost-lee-calcote-layer5-girish-ranganathan-solarwinds?iframe=no&w=100%&sidebar=yes&bg=no) | ([video](https://www.youtube.com/watch?v=LxP-yHrKL4M&list=PLYjO73_1efChX9NuRaU7WocTbgrfvCoPE), [deck](https://calcotestudios.com/talks/decks/slides-kubecon-eu-2019-service-meshes-at-what-cost.html)) | ||
| - Istio Founders Meetup @ KubeCon EU 2019 | [deck](https://calcotestudios.com/talks/decks/slides-istio-meetup-kubecon-eu-2019-istio-at-scale-large-and-small.html) | ||
| - [Cloud Native Rejekts EU 2019](https://cfp.cloud-native.rejekts.io/cloud-native-rejekts-eu-2019/speaker/GZQTEM/) | [deck](https://calcotestudios.com/talks/decks/slides-cloud-native-rejekts-2019-evaluating-service-meshes.html) | ||
| - [DockerCon 2019 Open Source Summit](https://dockercon19.smarteventscloud.com/connect/sessionDetail.ww?SESSION_ID=309149&tclass=popup#.XJxH-TOcbjI.twitter) | [deck](https://calcotestudios.com/talks/decks/slides-dockercon-2019-establishing-an-open-source-office.html), [video](https://www.docker.com/dockercon/2019-videos?watch=open-source-summit-service-mesh) | ||
| - [Container World 2019](https://tmt.knect365.com/container-world/speakers/lee-calcote) | [deck](https://calcotestudios.com/talks/decks/slides-container-world-2019-service-meshes-but-at-what-cost.html) | ||
| - [Service Mesh Day](https://servicemeshday.com/schedule.html) | [deck](https://docs.google.com/presentation/d/1HwG03okX3DHgGKbma4PL-MO7Xr9zDrjQgd05PRi9i8E/edit?usp=sharing), [video](https://youtu.be/CFj1O_uyhhs) | ||
| - [Innotech San Antonio](https://innotechsanantonio2019.sched.com/event/Lmlb/the-enterprise-path-to-service-mesh-architectures?iframe=no&w=100%&sidebar=yes&bg=no) | [deck](https://calcotestudios.com/talks/decks/slides-innotech-san-antonio-2019-the-enterprise-path-to-service-mesh.html) | ||
| - [CNCF Networking WG](https://github.com/cncf/wg-networking) | [deck](https://www.slideshare.net/leecalcote/benchmarking-service-meshes-cncf-networking-wg-141938576), [video](https://www.youtube.com/watch?v=2_JwCc-kLMA&list=PLYjO73_1efChX9NuRaU7WocTbgrfvCoPE) | ||
| --> |
Contributor
|
@sarika-03 |
Contributor
|
@sarika-03 Could you please update the PR title. |
sarika-03
changed the title
|
@sarika-03 Thank you for your contribution! Let's discuss this during the website call today at 6:30 PM IST | 7 AM CST Add it as an agenda item to the meeting minutes, if you would 🙂 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR improves the README with comprehensive setup and installation instructions for new contributors. The current README lacks clear guidance on how to get started, making it difficult for first-time contributors to set up and run the project locally.
**Fixes #112 **
Changes
Added Sections:
1. 🚀 Getting Started
cd site)site/→ install → run2. 📂 Project Structure
site/src/components/ShapeBuilder/)3. 🛠️ Available Scripts
npm start- Start development servernpm run build- Production buildnpm run lint- Code quality checksnpm run clean- Clear Gatsby cachenpm run serve- Serve production build4. 🐛 Troubleshooting
npm run cleansteps5. 💡 Enhanced Usage Instructions
6. 🤝 Improved Contributing Section
git commit -s)Improvements Made:
[X]Added emoji icons for better visual navigation
[X]Organized content with clear hierarchical headings
[X]Included code blocks for copy-paste convenience
[X]Added troubleshooting section for common issues
[X]Enhanced contribution workflow documentation
[X]Maintained existing community and license sections
[X]Professional formatting throughout
Root Cause
New contributors frequently struggle with:
package.jsonis insite/folder, not rootnpm installin wrong directorySolution
Comprehensive documentation that:
Testing
Screenshots
Before
Missing Setup Instructions:
Current README lacks setup, troubleshooting, and clear contribution guidelines
After
Comprehensive Getting Started Section:
New README includes step-by-step setup, project structure, scripts, troubleshooting, and contribution workflow
Example: New Getting Started Section
Example: Project Structure Section
Example: Troubleshooting Section
Impact
Benefits for Contributors:
Benefits for Maintainers:
Additional Context
This improvement addresses common pain points observed in:
The enhanced documentation follows patterns from successful CNCF projects and makes shape-builder more accessible to the global open-source community.
Notes for Reviewers
[Signed commits](https://github.com/meshery/meshery/blob/master/CONTRIBUTING.md#signing-off-on-commits-developer-certificate-of-origin)