Skip to main content
We welcome contributions from the community! Whether it’s bug fixes, new features, or documentation improvements, your help makes iStory better.

​
Getting Started

1

Fork the repository

Fork the iStory repository on GitHub
2

Clone your fork

git clone https://github.com/<your-username>/web3_Ai_eStory.git
cd i_story_dapp
3

Install dependencies

npm install
4

Create a feature branch

git checkout -b feature/your-short-description

​
Development Workflow

​
Branch Naming Convention

Use descriptive prefixes for your branches:

feature/

New features or enhancements
feature/add-story-export

fix/

Bug fixes
fix/audio-upload-error

docs/

Documentation updates
docs/update-api-reference

chore/

Maintenance tasks
chore/update-dependencies

​
Commit Messages

Follow Conventional Commits style: 
feat(record): add real-time transcription indicator
The format is: type(scope): description. Common types: feat, fix, docs, style, refactor, test, chore.

​
Code Style & Standards

​
Linting

The project uses ESLint and TypeScript. Run these before submitting: 
npm run lint        # Check for errors
npm run lint:fix    # Auto-fix issues

​
TypeScript Guidelines

// ❌ Bad
function saveStory(data: any) { ... }

// ✅ Good
interface StoryData {
  title: string;
  content: string;
  mood?: string;
}

function saveStory(data: StoryData) { ... }

// Define in app/types/index.ts
export interface Story {
  id: string;
  title: string;
  content: string;
  author_id: string;
  created_at: string;
}

// ❌ Avoid
const data = response as StoryData;

// ✅ Better - validate at runtime
import { z } from 'zod';
const StorySchema = z.object({
  title: z.string(),
  content: z.string(),
});
const data = StorySchema.parse(response);

​
React/Next.js Patterns

Server Components

Use for pages that fetch data (metadata, SEO)
// app/story/[id]/page.tsx
export default async function Page() {
  const data = await fetchData();
  return <StoryPageClient data={data} />;
}

Client Components

Use "use client" for interactive UI
// app/record/RecordPageClient.tsx
"use client";

export default function RecordPage() {
  const [recording, setRecording] = useState(false);
  // ...
}

​
Component Organization

// 1. Imports
import { useState } from "react";
import { Button } from "@/components/ui/button";

// 2. Types/Interfaces
interface Props {
  title: string;
  onSave: () => void;
}

// 3. Component
export function StoryCard({ title, onSave }: Props) {
  // 4. Hooks
  const [isLiked, setIsLiked] = useState(false);
  
  // 5. Event handlers
  const handleLike = () => {
    setIsLiked(!isLiked);
  };
  
  // 6. Render
  return (
    <div className="story-card">
      <h3>{title}</h3>
      <Button onClick={handleLike}>
        {isLiked ? "Liked" : "Like"}
      </Button>
    </div>
  );
}

​
Testing Requirements

​
Writing Tests

All new features should include tests: 
import { render, screen } from "@testing-library/react";
import { describe, it, expect } from "vitest";
import { StoryCard } from "../components/StoryCard";

describe("StoryCard", () => {
  it("renders story title", () => {
    render(<StoryCard title="My Story" onSave={() => {}} />);
    expect(screen.getByText("My Story")).toBeInTheDocument();
  });
});

​
Running Tests

Before submitting your PR: 
npx vitest run          # Unit tests
npx playwright test     # E2E tests
npm run build          # Production build
All tests must pass before your PR will be reviewed. Add new tests for new features.

​
Pull Request Process

1

Ensure quality checks pass

  • Linting passes (npm run lint)
  • All tests pass (npx vitest run)
  • Production build succeeds (npm run build)
  • Code follows existing patterns
2

Update documentation

If you’ve changed:
  • API routes → Update docs/API_REFERENCE.md
  • Database schema → Update docs/DATABASE_SCHEMA.md
  • Testing patterns → Update docs/TESTING_GUIDE.md
3

Create pull request

Push your branch and open a PR with:
  • Clear title describing the change
  • Detailed description of what and why
  • Screenshots for UI changes
  • Link to related issues
4

Address review feedback

Respond to reviewer comments and make requested changes

​
PR Template

## Description
Brief summary of changes and motivation.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How Has This Been Tested?
- [ ] Unit tests
- [ ] E2E tests
- [ ] Manual testing

## Screenshots (if applicable)

## Checklist
- [ ] Code follows the project's style guidelines
- [ ] Self-review completed
- [ ] Commented hard-to-understand areas
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added and passing
- [ ] Dependent changes merged and published

​
Contribution Guidelines

​
What to Contribute

Bug Fixes

Fix issues listed in GitHub Issues or bugs you discover

Features

Implement features from the roadmap or propose new ones

Documentation

Improve guides, add examples, fix typos

Tests

Increase test coverage, add edge cases

​
Before Starting Major Work

For significant features or breaking changes, open an issue first to discuss the design and scope. This prevents wasted effort if the approach isn’t aligned with the project direction.

​
Code of Conduct

Be respectful and inclusive. Follow the guidelines in CODE_OF_CONDUCT.md:
  • Use welcoming and inclusive language
  • Be respectful of differing viewpoints
  • Accept constructive criticism gracefully
  • Focus on what’s best for the community
  • Show empathy towards other community members

​
Security Issues

Do NOT open public issues for security vulnerabilities. Instead, email the maintainers at [email protected] with:
  • Detailed description of the vulnerability
  • Steps to reproduce
  • Potential impact
  • Suggested fix (if any)
Allow time for the team to respond and patch before public disclosure.

​
Community Resources

Discord

Join the community for questions and discussions

GitHub Discussions

Long-form discussions about features and architecture

Twitter/X

Follow @eStoryApp for updates

​
Development Environment

  • Editor: VS Code with ESLint and Prettier extensions
  • Node.js: Version 18 or higher
  • Package Manager: npm (comes with Node.js)
  • Wallet: MetaMask for Web3 testing
  • Database: Supabase account (free tier works)

​
Useful Commands

CommandDescription
npm run devStart development server
npm run buildBuild for production
npm run lintRun ESLint checks
npx vitestRun tests in watch mode
npx playwright test --uiRun E2E tests with UI
npx hardhat compileCompile smart contracts

​
Recognition

All contributors are recognized in the project README and release notes. Thank you for making iStory better! 🎙️📚

​
Questions?

If you have questions about contributing:
  1. Check existing GitHub Discussions
  2. Ask in the Discord community
  3. Open a new discussion for general questions
  4. Only open issues for specific bugs or feature requests

Build docs developers (and LLMs) love

Get started for freeTalk to us