Skip to content

Commit 1d69219

Browse files
AykutSaracAykutSarac
committed
chore: add pull request template to guide contributors
1 parent eaafbf5 commit 1d69219

File tree

2 files changed

+146
-36
lines changed

2 files changed

+146
-36
lines changed

‎.github/pull_request_template.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
## Issue
2+
Closes #[ISSUE_NUMBER]
3+
4+
## What Changed
5+
Brief description of what you changed and why.
6+
7+
Example:
8+
- Added JSON validation tooltip on parse error
9+
- Improved performance by memoizing graph component
10+
- Fixed bug where large JSON files caused slowdown
11+
12+
## How to Test
13+
Step-by-step instructions to test the change:
14+
15+
1. ...
16+
2. ...
17+
3. ...
18+
19+
## Evidence
20+
**Screenshots or Video Required** — Choose one or both:
21+
22+
### Screenshots
23+
- [ ] Before/after screenshots attached (for UI changes)
24+
25+
### Video
26+
- [ ] Screen recording of the feature in action
27+
28+
### Testing
29+
- [ ] Tested locally with `pnpm dev`
30+
- [ ] No console errors
31+
- [ ] Tested with large JSON files (if applicable)
32+
33+
## Performance Impact
34+
Any notes on performance, re-renders, or potential concerns?
35+
36+
- [ ] No performance impact
37+
- [ ] Improved performance (explain how)
38+
- [ ] Potential impact (explain and justify)
39+
40+
## Additional Notes
41+
Anything else reviewers should know?
42+
43+
---
44+
45+
**Remember:** If this PR is not linked to an issue, it may be closed. Always reference an approved issue!

‎CONTRIBUTING.md‎

Lines changed: 101 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,129 @@
1-
# Welcome to the JSON Crack Contributing Guide <!-- omit in toc -->
1+
# Contributing to JSON Crack
22

3-
Thank you for investing your time in contributing to our project! Any contribution you make will be reflected at [jsoncrack.com](https://jsoncrack.com).
3+
Thank you for wanting to contribute! This is a community-driven project, and we appreciate your help. Please read this guide carefully to make the review process smooth and fast.
44

5-
Read our [Code of Conduct](./CODE_OF_CONDUCT.md) to keep our community approachable and respectable.
5+
**Read our [Code of Conduct](./CODE_OF_CONDUCT.md) first** — we want to keep this community friendly and welcoming.
66

7-
In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.
7+
---
88

9-
## Getting Started
10-
JSON Crack is built with React, Reaflow for visualization, Mantine UI for components, Zustand for state management. If you are not familiar with these technologies, we recommend you to read their documentation to get started. You can find the links to the respective documentations below:
9+
## Before You Start: The Issue-First Workflow
1110

12-
* [React](https://reactjs.org/docs/getting-started.html)
13-
* [Reaflow](https://github.com/reaviz/reaflow)
14-
* [Mantine UI](https://mantine.dev/)
15-
* [Zustand](https://github.com/pmndrs/zustand)
11+
**Always open or find an issue BEFORE you start coding.** This saves everyone time.
1612

17-
If you're looking for a task to contribute, you can pick up a TODO from our project board: [Open Project Board Tasks](https://github.com/AykutSarac/jsoncrack.com/projects?query=is%3Aopen).
13+
1. **Check existing issues** — Search to see if someone already reported this or is working on it
14+
2. **Open a new issue** if one doesn't exist — Describe what you want to fix or build
15+
3. **Wait for approval** — I'll review and give feedback (usually within a few days)
16+
4. **Once approved**, you can start coding
17+
5. **Link your PR to the issue** — Use `Closes #123` in your PR description
1818

19-
Once you are familiar with these technologies, you can clone the JSON Crack repository by running the following command:
19+
This workflow prevents duplicate work and ensures your contribution aligns with the project's direction.
2020

21-
```bash
22-
git clone https://github.com/AykutSarac/jsoncrack.com.git
23-
```
21+
---
2422

25-
After cloning the repository, you can install the required dependencies by running the following command:
23+
## Quick Setup
2624

25+
### Prerequisites
26+
- Node.js 18+
27+
- pnpm (or npm/yarn)
28+
29+
### Tech Stack
30+
JSON Crack uses:
31+
- **React** — UI library
32+
- **Reaflow** — Graph visualization
33+
- **Mantine UI** — UI components
34+
- **Zustand** — State management
35+
36+
### Get Started
2737
```bash
38+
# Clone the repo
39+
git clone https://github.com/AykutSarac/jsoncrack.com.git
40+
cd jsoncrack.com
41+
42+
# Install dependencies
2843
pnpm install
44+
45+
# Run the dev server
46+
pnpm dev
2947
```
3048

31-
To run the development server, you can run the following command:
49+
The app will be available at `http://localhost:3000`
50+
51+
---
52+
53+
## How to Submit a Pull Request
54+
55+
### Requirements
56+
Before submitting, make sure your PR includes:
3257

58+
1. **Issue ID** — Reference the issue: `Closes #123`
59+
2. **Clear description** — What does this change do? Why?
60+
3. **Evidence of working changes** — One or both:
61+
- **Screenshot** — Show the UI before/after
62+
- **Video** — Screen recording of the feature in action
63+
4. **Test it locally** — Run `pnpm dev` and verify it works
64+
5. **Follow code style** — Use [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)
65+
66+
### Creating Your Branch
3367
```bash
34-
pnpm dev
68+
git checkout -b fix/issue-123-description
69+
# or
70+
git checkout -b feature/issue-123-description
3571
```
3672

37-
## Contributing Guidelines
38-
Before submitting a pull request, please make sure to follow these guidelines:
73+
Use clear branch names that reference the issue.
74+
75+
---
76+
77+
## Guidelines
78+
79+
### Performance First
80+
- Avoid unnecessary re-renders
81+
- Use React DevTools Profiler to check performance
82+
- Test with large JSON files to ensure no slowdowns
83+
84+
### Code Quality
85+
- Follow the [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)
86+
- Write descriptive commit messages
87+
- Keep changes focused — one feature/fix per PR
3988

40-
### 1. Performance
41-
Performance is an important criteria for JSON Crack. Any new contributions should not affect the re-rendering of the application. Therefore, when making changes to the code, please keep performance in mind.
89+
### Testing
90+
- Manually test your changes thoroughly
91+
- Describe exactly how you tested it in the PR
92+
- Make sure existing features still work
4293

43-
If you're having trouble with re-rendering issues in React, you can use the React Devtools Profiler to debug it. You can also check out this up-to-date guide on debugging re-renders with React Devtools to learn more.
94+
---
4495

45-
### 2. Code Style
46-
We follow the [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html) for our code. Please make sure to follow this guide when writing new code or modifying existing code.
96+
## Example PR
4797

48-
### 3. Testing
49-
While we do not currently have a comprehensive testing suite in place, we encourage contributors to thoroughly test their changes and ensure that they do not break any existing functionality. Please include a description of how you tested your changes in your pull request, so that we can review them more effectively.
98+
Here's what a good PR looks like:
5099

51-
### 4. Commit Messages
52-
Please use descriptive commit messages that explain the changes you have made. This will help us understand your changes and make it easier to review your pull request.
100+
**Title:** Add JSON validation tooltip on parse error
53101

54-
### 5. Pull Requests
55-
Please create a new branch for your changes and submit a pull request to the main branch. Please provide a detailed explanation of the changes you have made and any necessary context in the pull request description.
102+
**Description:**
103+
```
104+
Closes #234
105+
106+
## What Changed
107+
Added a helpful tooltip that shows validation errors when JSON fails to parse, making it easier for users to fix their JSON.
108+
109+
## How to Test
110+
1. Paste invalid JSON: `{invalid`
111+
2. Look for the red error indicator
112+
3. Hover over it to see the detailed error message
113+
114+
## Evidence
115+
- [Screenshot of tooltip](link-to-image)
116+
117+
## Performance Notes
118+
No performance impact. Tooltip renders conditionally only on errors.
119+
```
56120

57-
## Conclusion
58-
We appreciate any contributions to JSON Crack, big or small. If you have any questions or need any help, please do not hesitate to reach out to us. Thank you for contributing!
121+
---
59122

60-
### Your PR is merged!
123+
## Questions?
61124

62-
Congratulations :tada::tada: The JSON Crack team thanks you :sparkles:.
125+
- Found a bug? Open an issue
126+
- Have an idea? Open an issue
127+
- Confused about something? Comment on the issue
63128

64-
Once your PR is merged, your contributions will become part of the next JSON Crack release, and will be visible in the [JSON Crack app](https://jsoncrack.com).
129+
Thank you for contributing to JSON Crack! 🎉

0 commit comments

Comments
 (0)