Skip to content

Fix : README Add Missing Setup Instructions, Troubleshooting, and Contribution Workflow Add Missing Setup Instructions, Troubleshooting, and Contribution Workflow #121

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.

Sign up for GitHub

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

Closed
sarika-03 wants to merge 7 commits into from
Closed

Fix : README Add Missing Setup Instructions, Troubleshooting, and Contribution Workflow Add Missing Setup Instructions, Troubleshooting, and Contribution Workflow #121

Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5b79fa5
[Docs] Improve README with setup instructions for new contributors #112
sarikasharma2428-web Dec 30, 2025
f6a4e01
[Docs] Improve README with setup instructions for new contributors #112
sarikasharma2428-web Dec 30, 2025
c6cba52
[Docs] Improve README with setup instructions for new contributors #112
sarikasharma2428-web Dec 30, 2025
446fa55
Merge branch 'master' into doc
saurabhraghuvanshii Jan 9, 2026
5f5f3f3
Merge branch 'master' into doc
sarika-03 Jan 12, 2026
7d058b7
Apply suggestion from @saurabhraghuvanshii
fitzergerald Apr 10, 2026
5da5c4a
Merge branch 'master' into doc
fitzergerald Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
293 changes: 253 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@

<p style="text-align:center;" align="center"><a href="https://meshery.io"><picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/meshery/meshery/master/.github/assets/images/readme/meshery-logo-light-text-side.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/meshery/meshery/master/.github/assets/images/readme/meshery-logo-dark-text-side.svg">
<img src="https://raw.githubusercontent.com/meshery/meshery/master/.github/assets/images/readme/meshery-logo-dark-text-side.svg"
alt="Meshery Logo" width="70%" /></picture></a><br /><br /></p>

<p align="center">
<a href="https://hub.docker.com/r/meshery/meshery" alt="Docker pulls">
<img src="https://img.shields.io/docker/pulls/layer5/meshery.svg" /></a>
Expand All @@ -27,13 +27,11 @@ alt="Meshery Logo" width="70%" /></picture></a><br /><br /></p>
<img src="https://img.shields.io/twitter/follow/mesheryio.svg?label=Follow+Meshery&style=social" /></a>
<a href="https://github.com/meshery/meshery/releases" alt="Meshery Downloads">
<img src="https://img.shields.io/github/downloads/meshery/meshery/total" /></a>
<!-- <a href="https://app.fossa.com/projects/git%2Bgithub.com%2Fmeshery%2Fmeshery?ref=badge_shield" alt="License Scan Report">
<img src="https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmeshery%2Fmeshery.svg?type=shield"/></a>
-->
</p>

<h5><p align="center"><i>If you like Meshery, please <a href="https://github.com/meshery/meshery/stargazers">★</a> this repository to show your support! 🤩</i></p></h5>
<p align="center" >

<p align="center">
MESHERY IS A CLOUD NATIVE COMPUTING FOUNDATION PROJECT
</p>

Expand All @@ -42,8 +40,9 @@ MESHERY IS A CLOUD NATIVE COMPUTING FOUNDATION PROJECT
<img src="https://raw.githubusercontent.com/meshery-extensions/shape-builder/98531eecdd2c5b01895f1d818f824bf186bf6077/.github/assets/images/readme/cncf-black.svg#gh-light-mode-only" width="30%" align="center" />
</div>
<br />

<p align="center">
A self-service engineering platform, <a href="https://meshery.io">Meshery</a>, is the open source, cloud native manager that enables the design and management of all Kubernetes-based infrastructure and applications (multi-cloud). Among other features, As an extensible platform, Meshery offers visual and collaborative GitOps, freeing you from the chains of YAML while managing Kubernetes multi-cluster deployments.
A self-service engineering platform, <a href="https://meshery.io">Meshery</a>, is the open source, cloud native manager that enables the design and management of all Kubernetes-based infrastructure and applications (multi-cloud). Among other features, As an extensible platform, Meshery offers visual and collaborative GitOps, freeing you from the chains of YAML while managing Kubernetes multi-cluster deployments.
</p>
<br />

Expand All @@ -57,35 +56,268 @@ A self-service engineering platform, <a href="https://meshery.io">Meshery</a>, i

<img src="https://raw.githubusercontent.com/meshery-extensions/shape-builder/98531eecdd2c5b01895f1d818f824bf186bf6077/.github/assets/images/site.png" width="100%" align="center" />

This Meshery extension offers an easy way to visually create polygons, outputting the format necessary for Kanvas to recognize and render your custom polygon shape. As a best practice, users are encouraged to select an existing or create acustom shape for their components to best visually signify the function of their component. See the [Components Shape Guide](https://docs.meshery.io/extensions/component-shape-guide) for a list of the built-in component shapes in Meshery.
This Meshery extension offers an easy way to visually create polygons, outputting the format necessary for Kanvas to recognize and render your custom polygon shape. As a best practice, users are encouraged to select an existing or create a custom shape for their components to best visually signify the function of their component. See the [Components Shape Guide](https://docs.meshery.io/extensions/component-shape-guide) for a list of the built-in component shapes in Meshery.

Interactively, explore existing component shapes easily by looking in [Meshery Playground](https://play.meshery.io) in the Kanvas extension's on the dock at the bottom of the screen. You will see the different types of component shapes in the "Shapes" model as examples.

## Usage
<div>&nbsp;</div>

## 🚀 Getting Started

### Prerequisites

Before you begin, ensure you have the following installed:

- **Node.js** (v16 or higher) - [Download](https://nodejs.org/)
- **npm** (v8 or higher) - Comes with Node.js
- **Git** - [Download](https://git-scm.com/)
- **make** (optional) - Pre-installed on most Linux and macOS systems

### Installation & Setup

#### 1. Clone the Repository

```bash
git clone https://github.com/meshery-extensions/shape-builder.git
cd shape-builder
```

#### 2. Navigate to Site Directory

The main application code is located in the `site/` directory:

```bash
cd site
```

#### 3. Install Dependencies

```bash
npm install
```

#### 4. Start Development Server

```bash
npm start
```

Or alternatively:

```bash
npm run develop
```

The application will be available at: **http://localhost:8000**

### 📂 Project Structure

```
shape-builder/
├── .github/ # GitHub workflows and configurations
├── .vscode/ # VS Code settings
├── build/ # Build output directory
├── site/ # Main application code (START HERE!)
│ ├── src/
│ │ ├── components/ # React components
│ │ │ ├── Footer/
│ │ │ ├── Navigation/
│ │ │ └── ShapeBuilder/ # Main shape builder component
│ │ ├── pages/ # Page components
│ │ └── styles/ # Global styles
│ ├── package.json # Dependencies and scripts
│ └── gatsby-config.js # Gatsby configuration
├── README.md
└── LICENSE
```

### 🛠️ Available Scripts

Once inside the `site/` directory, you can run:

| Command | Description |
|---------|-------------|
| `npm start` | Start development server on http://localhost:8000 |
| `npm run develop` | Same as `npm start` |
| `npm run build` | Build the production-ready site |
| `npm run serve` | Serve the production build locally |
| `npm run clean` | Clean Gatsby cache and public directory |
| `npm run lint` | Run linter to check code quality |

### 🔧 Using Make Commands (Optional)

For contributors who prefer using `make` instead of running individual `npm` commands, this project provides a Makefile with commonly used commands to simplify setup and development.

#### Quick Start with Make

```bash
# Clone the repository
git clone https://github.com/meshery-extensions/shape-builder.git
cd shape-builder

# Install dependencies
make setup

# Run the project locally
make run
Comment thread
fitzergerald marked this conversation as resolved.
Outdated
```

#### Available Make Commands

| Command | Description |
|---------|-------------|
| `make help` | Display all available make commands |
| `make setup` | Install all required dependencies |
| `make run` | Start the local development server |
Copy link
Copy Markdown
Member

@saurabhraghuvanshii saurabhraghuvanshii Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `make run` | Start the local development server |
| `make site` | Start the local development server |

| `make build` | Create a production build |
| `make clean` | Clean Gatsby cache and build artifacts |
| `make lint` | Run linting checks |

### 🐛 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
```

Comment on lines +176 to +211
Copy link
Copy Markdown
Member

@saurabhraghuvanshii saurabhraghuvanshii Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
```

Copy link
Copy Markdown
Member

@saurabhraghuvanshii saurabhraghuvanshii Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sarika-03 no need of this

<div>&nbsp;</div>

## 💡 Usage

Once you have created your custom shape, export your matrix notation and use within a `polygon` shape in your Meshery Component. For example, the following is a plus icon:

### How to Create a Custom Shape

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
Copy link
Copy Markdown
Member

@saurabhraghuvanshii saurabhraghuvanshii Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
3. **Close the Shape** - Double-click or click "Close Shape" button
3. **Close the Shape** - Enter or ESC

4. **Get Coordinates** - Copy the generated coordinates from the output box
5. **Use in Meshery** - Paste the coordinates in your Meshery component definition

#### Custom Shape Example

![Image](https://github.com/user-attachments/assets/4d022a7a-bb78-44e3-9c95-f36b47bd2c97)

**Generated Coordinates:**
```
-0.33 -1 0.33 -1 0.33 -0.33 1 -0.33 1 0.33 0.33 0.33 0.33 1 -0.33 1 -0.33 0.33 -1 0.33 -1 -0.33 -0.33 -0.33
```

### Keyboard Shortcuts

- **Ctrl + Click** - Snap to precise grid (fine control)
- **Enter** or **Escape** - Close current shape
- **Ctrl + Z** - Undo last point
- **Double Click** - Close shape

### Additional Details

Anyone can create new components. When they do, they can use a predefined shape to represent their new component. Alternatively, they can define their own polygon; their own shape. The manner in which shapes are defined is based on a number matrix from negative one to positive one.

<div>&nbsp;</div>

## 🤝 Contributing

We welcome contributions! Here's how you can help:

### For New Contributors

1. **Fork the repository** - Click the "Fork" button at the top right
2. **Clone your fork**
```bash
git clone https://github.com/YOUR_USERNAME/shape-builder.git
cd shape-builder/site
```
3. **Create a branch**
```bash
git checkout -b feature/your-feature-name
```
4. **Make your changes** - Edit files in `site/src/`
5. **Test your changes**
```bash
npm start
```
6. **Commit with sign-off**
```bash
git add .
git commit -s -m "[Component] Description of changes"
```
7. **Push to your fork**
```bash
git push origin feature/your-feature-name
```
8. **Create a Pull Request** - Go to the original repository and click "New Pull Request"

### Contribution Guidelines

- ✅ Follow the existing code style
- ✅ Write clear commit messages
- ✅ Sign your commits (`git commit -s`)
- ✅ Test your changes before submitting
- ✅ Include screenshots for UI changes
- ✅ Reference related issues in your PR

Please read our [Contributor Guides](https://docs.meshery.io/project/contributing) for more details.

### 📝 Commit Message Format

```
[Component] Brief description

Detailed explanation of what changed and why.

Fixes #issue_number
```

Example:
```
[ShapeBuilder] Fix copy button visibility with long coordinates

Changed button positioning from absolute to sticky with flexbox layout
to ensure visibility regardless of coordinate length.

Fixes #89
```

<div>&nbsp;</div>

## Join the Meshery community!

<a name="contributing"></a><a name="community"></a>
<a name="community"></a>
Our projects are community-built and welcome collaboration. 👍 Be sure to see the <a href="https://layer5.io/community/newcomers">Contributor Journey Map</a> and <a href="https://meshery.io/community#handbook">Community Handbook</a> for a tour of resources available to you and the <a href="https://layer5.io/community/handbook/repository-overview">Repository Overview</a> for a cursory description of repository by technology and programming language. Jump into community <a href="https://slack.meshery.io">Slack</a> or <a href="https://meshery.io/community#discussion-forums">discussion forum</a> to participate.

<p style="clear:both;">

<a href ="https://meshery.io/community/meshmates"><img alt="MeshMates" src="https://meshery.io/assets/images/logos/meshmate-light.svg" style="margin-right:36px; margin-bottom:7px;" width="140px" align="left" /></a>
<a href="https://meshery.io/community/meshmates"><img alt="MeshMates" src="https://meshery.io/assets/images/logos/meshmate-light.svg" style="margin-right:36px; margin-bottom:7px;" width="140px" align="left" /></a>

<h3>Find your MeshMate</h3>

Expand All @@ -95,6 +327,7 @@ Learn more about the <a href="https://meshery.io/community#meshmates">MeshMates<

</p>
<br /><br />

<div style="display: flex; justify-content: center; align-items:center;">
<div>
<a href="https://meshery.io/community"><img alt="Cloud Native Community" src="https://docs.meshery.io/assets/img/readme/community.png" width="140px" style="margin-right:36px; margin-bottom:7px;" width="140px" align="left"/></a>
Expand All @@ -112,57 +345,37 @@ Learn more about the <a href="https://meshery.io/community#meshmates">MeshMates<
<div>
<a href="https://slack.meshery.io">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/meshery/meshery/master/.github/assets/images/readme/slack.svg" width="110px" />
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/meshery/meshery/master/.github/assets/images/readme/slack.svg" width="110px" />
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/meshery/meshery/master/.github/assets/images/readme/slack.svg" width="110px" />
<img alt="Shows an illustrated light mode meshery logo in light color mode and a dark mode meshery logo dark color mode." src="https://raw.githubusercontent.com/meshery/meshery/master/.github/assets/images/readme/slack.svg" width="110px" align="left" />
</picture>
</a>
</div>
</div>
<br /><br />

<p align="left">
&nbsp;&nbsp;&nbsp;&nbsp; <i>Not sure where to start?</i> Grab an open issue with the <a href="https://github.com/issues?q=is%3Aopen%20is%3Aissue%20archived%3Afalse%20(repo%3Alayer5io%2Flayer5%20OR%20repo%3Ameshery%2Fmeshery%20OR%20repo%3Aservice-mesh-performance%2Fservice-mesh-performance%20OR%20repo%3Aservice-mesh-patterns%2Fservice-mesh-patterns)%20label%3A%22help%20wanted%22">help-wanted label</a>.
</p>
<br /><br />

<div>&nbsp;</div>

## Contributing

Please do! We're a warm and welcoming community of open source contributors. Please join. All types of contributions are welcome. Be sure to read the [Contributor Guides](https://docs.meshery.io/project/contributing) for a tour of resources available to you and how to get started.

<!-- <a href="https://youtu.be/MXQV-i-Hkf8"><img alt="Deploying Linkerd with Meshery" src="https://docs.meshery.io/assets/img/readme/deploying-linkerd-with-meshery.png" width="100%" align="center" /></a> -->

<div>&nbsp;</div>

### Stargazers
## 📊 Stargazers

<p align="center">
<i>If you like Meshery, please <a href="../../stargazers">★</a> star this repository to show your support! 🤩</i>
<i>If you like Meshery, please <a href="../../stargazers">★</a> star this repository to show your support! </i>
<br />
<a href="../../stargazers">
<img align="center" src="https://api.star-history.com/svg?repos=meshery/meshery&type=Date" />
<img align="center" src="https://api.star-history.com/svg?repos=meshery-extensions/shape-builder&type=Date" />
</a></p>

### License
## 📄 License

This repository and site are available as open-source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).

---

<!--### 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)
-->
Comment on lines -152 to -168
Copy link
Copy Markdown
Member

@saurabhraghuvanshii saurabhraghuvanshii Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sarika-03 revert this

<p align="center">
Made with ❤️ by the Meshery community
</p>