Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
262 lines (200 loc) · 9.61 KB

CONTRIBUTING.md

File metadata and controls

262 lines (200 loc) · 9.61 KB

Contributing to GroqTales

SWOC'26 GSSOC'25 FOSS Hack LGM-SOC MLH HackinCodes cWoc Indie Hub Open Source Community

Thank you for your interest in contributing to GroqTales, an AI-powered Web3 storytelling platform! We welcome developers, writers, designers, and blockchain enthusiasts to help us build a creative, open, and secure platform. Please read this guide before getting started.

Table of Contents

SWOC'26 Participation

Are you contributing as part of Social Winter of Code (SWOC) 2026? Please see our SWOC'26.md for program-specific guidelines, point systems, and communication channels.

Note: Ensure your PRs are tagged with the SWOC'26 label to be eligible for program points.

Code of Conduct

We are committed to providing a welcoming and inclusive environment for everyone. By participating, you agree to:

  • Be respectful of different viewpoints and experiences.
  • Gracefully accept constructive criticism.
  • Focus on what is best for the community and project.
  • Show empathy toward other community members.

For more, see CODE_OF_CONDUCT.md.

How Can I Contribute?

You can contribute in several ways:

  • Reporting Bugs: Use the bug_report.md template and provide detailed steps to reproduce.
  • Suggesting Features: Use the feature.md template to propose new ideas.
  • Code Contributions: Pick up issues labeled good first issue.
  • Web3/Blockchain: Use the web3_issue.md template for Monad/NFT-related contributions.
  • Security: Use the security.md template for vulnerabilities.
  • Documentation: Help improve the README, Wiki, or code comments.

Using Issue Templates

Before opening any issue or pull request, you must use the relevant template provided in .github/ISSUE_TEMPLATE/. Please fill out all required sections to help us triage and resolve your issue quickly. Templates include:

  • bug_report.md – For bugs or unexpected behavior
  • feature.md – For new features or enhancements
  • web3_issue.md – For blockchain/NFT/Web3-specific issues
  • security.md – For vulnerabilities or security concerns
  • basic.md – For small tasks, typos, or minor requests
  • other.md – For anything not covered above

Please fill out all required sections in the template to help us triage and resolve your issue quickly.

Development Setup

To get started with development:

  1. Clone the Repository:

    git clone [https://github.com/IndieHub25/GroqTales.git](https://github.com/IndieHub25/GroqTales.git)
cd GroqTales

  2. Install Dependencies:

    npm install

  3. Environment Variables: Copy .env.example to .env.local and fill in:

  • GROQ_API_KEY – Groq AI key (required)
  • MONAD_RPC_URL – Monad blockchain endpoint
  • UNSPLASH_API_KEY – (Optional) for placeholder visuals
  1. Run Development Server: 
    npm run dev

Visit http://localhost:3000 in your browser.

Repository Structure & Architecture

GroqTales is organized for scalability and modularity. Here’s a high-level overview:

GroqTales/
│
├── .github/              # Issue templates, workflows, configs
├── app/                  # Next.js app (pages, routing, layouts)
├── components/           # Reusable React UI components
├── contracts/            # Solidity smart contracts for NFT minting
├── lib/                  # Utilities, API integrations, helpers
├── public/               # Static assets (images, icons, etc.)
├── scripts/              # Deployment and automation scripts
├── test/                 # Contract tests (e.g., Hardhat/Foundry)
├── tests/                # Frontend/backend test cases
├── types/                # Shared TypeScript types/interfaces
├── wiki/                 # Project Wiki and guides
├── .env.example          # Example environment variables
├── package.json          # Project dependencies and scripts
├── tailwind.config.js    # TailwindCSS config
├── README.md             # Main project overview
├── CONTRIBUTING.md       # Contribution guidelines
├── CONTRIBUTORS.md       # List of contributors
├── SECURITY.md           # Security policy
└── ...                   # Other config and support files

Architecture Notes

  • Frontend: Built with Next.js, React, TailwindCSS, and shadcn/ui for a modern, responsive UI.
  • Backend: Node.js API routes handle authentication, story generation, and blockchain interactions.
  • Blockchain: Monad SDK and Solidity smart contracts manage NFT minting and ownership.
  • AI: Groq API powers story and comic generation.
  • Database: MongoDB stores user data, stories, and metadata.
  • Testing: Jest/React Testing Library for frontend; Hardhat/Foundry for smart contracts.

Coding Guidelines

  • JavaScript/TypeScript: Follow the Airbnb Style Guide.
  • React/Next.js: Use functional components and hooks. Follow Next.js routing and data-fetching conventions.
  • Formatting: Use Prettier (npm run format).
  • Linting: Use ESLint (npm run lint).
  • Commits: Use descriptive commit messages (Conventional Commits format preferred).
  • Docs: Update docs and inline comments for all major changes.

Pull Request Process

  1. Fork the repository (do not branch from upstream directly).

  2. Clone your fork locally:

    git clone https://github.com/<your-username>/GroqTales.git
cd GroqTales
git remote add upstream https://github.com/IndieHub25/GroqTales.git

  3. Synchronize before starting work:

    git fetch upstream
git checkout main
git merge upstream/main

  4. Create a feature branch (use descriptive, kebab or slash style):

    git checkout -b feature/improve-story-generator

  5. Implement changes (small, atomic commits – use Conventional Commit style if possible).

  6. Run quality gates locally:

    npm run lint
npm run type-check
npm test

  7. Rebase onto upstream/main before opening PR:

    git fetch upstream
git rebase upstream/main

  8. Push to your fork:

    git push -u origin feature/improve-story-generator

  9. Open a Pull Request:

  • Base: IndieHub25/GroqTales main
  • Head: your-username:feature/improve-story-generator
  • Fill out PR template completely
  • Link issue with Fixes #<number> where applicable
  1. Address review feedback and keep branch rebased (avoid merge commits).
  2. PR Merge Policy: squash or rebase merges preferred; maintainers handle final merge.
  3. After merge: sync your fork: 
    git checkout main
git fetch upstream
git merge upstream/main
git push origin main

Testing Guidelines

  • Write or update tests for new features and bug fixes.
  • Frontend: Use Jest and React Testing Library.
  • Smart Contracts: Use Hardhat or Foundry for Solidity tests.
  • Ensure all tests pass before submitting a PR.
  • If unsure how to test a feature, ask in your PR or on Discord.

Labeling & Tagging

To ensure your contributions are tracked for SWOC'26, use the following labels:

  • Program: SWOC'26 (Mandatory for points)
  • Difficulty: SWOC-Level-1, SWOC-Level-2, SWOC-Level-3
  • Area: frontend, backend, blockchain, AI/LLM
  • Status: good first issue, help wanted

Documentation

  • Update or add documentation for any new features or changes.
  • Add inline comments for complex logic.
  • Keep the Wiki up to date for setup, usage, and architecture.

Community & Support

Thank you for contributing to GroqTales! If you have any questions, open an issue, ask in Discord, or contact the maintainers directly.