Add Contribution Guidelines `CONTRIBUTING.md`

[iamDyeus]

Create a well-structured CONTRIBUTING.md file to establish clear contribution guidelines. This should enforce a standardized branch workflow and ensure that all contributors follow the Commitizen convention for commit messages.

Branch Workflow Guidelines

The contributing guide should include the following branching strategy to maintain a clean and organized repository:

main → Production-ready code. Do not push directly.
dev → All features and bug fixes should be merged and tested here before being pushed to main.
feat/feature-name → New feature branches (e.g., feat/user-auth).
fix/bug-description → Bug fix branches (e.g., fix/navbar-issue).
hotfix/critical-bug-name → Critical production bug fixes (e.g., hotfix/payment-error).
refactor/module-name → Code improvements and optimizations (e.g., refactor/api-cleanup).

Commit Message Standard (Commitizen Enforcement)

• Ensure Commitizen is enforced across the repo.
• Contributors must use git cz instead of git commit to maintain a consistent commit format.

[vishalpawarR]

Hey! I will work on this issue! fine?

[iamDyeus]

Hey! I will work on this issue! fine?

Okay, go ahead. Make sure you follow the standards and requests above. 👍🏻

[vishalpawarR]

Sure! I will add them!

[vishalpawarR]

I have added this file:

https://github.com/vishalpawarR/wstack/tree/docs/contributing-markdown

I am looking at the husky Commitizen Enforcement

[vishalpawarR]

@iamDyeus let me know what you think of the current contribution file?

[iamDyeus]

Hey, I checked them out—thanks for sharing! Unfortunately, they don’t quite align with what we’re looking for at the moment. They seem a bit too generic and small, and I also noticed there aren’t any clear guidelines on how to contribute, which is a key purpose of a CONTRIBUTING.md file.

---

below are some guidelines you can add to it:

Some Common Guidelines

Wstack Docs

File-structure

Avoid placing all your components directly within a single file at the root of your project. Instead, create a _components directory within the same folder as your page-specific files.

project-root/
├── login/
│   ├── page.tsx          (Login page file)
│   ├── _components/
│   │   ├── LoginForm.tsx    (Login form component)
│   │   ├── PasswordInput.tsx (Password input component)
│   │   └── index.tsx       (Exports all components)
├── home/
│   ├── page.tsx
│   └── _components/
│       ├── HeroSection.tsx
│       ├── FeatureList.tsx
│       └── index.tsx
└── ...other pages and directories

Dealing with Forms

We need to follow a standard approach when working with forms to maintain consistency and protect both the frontend and backend. The recommended approach uses:

• ShadCN forms as the wrapper.
• Zod for validation.
• React Hook Form for managing form state.

Steps:

1. Use React-Hook-Form to along with your zod schema

  const form = useForm<z.infer<typeof validationSchema>>({
    resolver: zodResolver(validationSchema),
    defaultValues: {
      userId: '',
      password: '',
    },
  })

2. Define your mutations

3. use ShadCn Forms throughout
   Example:

<Form {...form}>
  <form
    className="space-y-4"
    onSubmit={form.handleSubmit((data) =>
      signInMutation.mutate(data),
    )}
  >
    <FormField
      control={form.control}
      name="userId"
      render={({ field }) => (
        <FormItem>
          <FormLabel className="text-sm">User ID</FormLabel>
          <FormControl>
            <Input
              {...field}
              type="text"
              required
              className="h-12 text-sm"
              placeholder="Enter your user ID"
            />
          </FormControl>
          <FormMessage className="text-xs" />
        </FormItem>
      )}
    />

Following this approach helps keep our MongoDB clean and optimized. Refer to this article for more details.

Using useState & useEffect Effectively

Do not overuse useState and useEffect. Many cases can be handled with derived state, context, or event handlers instead of unnecessary state management. Read this guide to understand when you actually need effects.

API Calls: Use Tanstack Only!

For API calls, always use Tanstack Query. This ensures better caching, structured data fetching, and a maintainable codebase.

Code Formatting & Linting

The starter kit includes scripts for linting and formatting. Before raising a PR:

1. Configure VS Code with Prettier.
2. Manually run linting and formatting using:

   pnpm run lint && pnpm run format

PR Types

We categorize PRs into four types:

• feat – New features
• fix – Bug fixes
• refactor – Code improvements without changing functionality
• hotfix – Urgent fixes

Code Commenting

Avoid excessive comments in the code. Only add comments when absolutely necessary for clarity.

Standardized Commits with CZCommit

Use CZCommit for commits to ensure a standardized commit message format across the repository.