TendSocial

Appearance

Thank you for your interest in contributing to TendSocial! This document provides guidelines and instructions for contributing to the project.

Table of Contents ​

Code of Conduct ​

Our Standards ​

  • Be respectful: Treat everyone with respect and kindness
  • Be constructive: Provide helpful feedback and suggestions
  • Be collaborative: Work together to improve the project
  • Be patient: Remember that everyone is learning

Unacceptable Behavior ​

  • Harassment, discrimination, or offensive comments
  • Trolling or deliberately derailing discussions
  • Publishing others' private information
  • Spam or irrelevant content

Getting Started ​

Prerequisites ​

  • node.js 24.x
  • pnpm 10.x
  • Git
  • Google Cloud API key (for AI features)
  • Basic knowledge of React, TypeScript, and REST APIs

Fork and Clone ​

  1. Fork the repository on GitHub
  2. Clone your fork locally:
    bash
    git clone https://github.com/YOUR_USERNAME/tendsocial.git
cd tendsocial
  3. Add upstream remote:
    bash
    git remote add upstream https://github.com/marcmontecalvo/tendsocial.git

Install Dependencies ​

bash
# Install all dependencies (root, apps, packages)
pnpm install

Configure Environment ​

bash
# Frontend
cp apps/frontend/.env.example apps/frontend/.env
# Edit .env and add your Google API key

# Backend
cp apps/backend/.env.example apps/backend/.env
# Add database URL and other secrets

Run Development Servers ​

bash
# Start both frontend and backend
pnpm dev

Visit http://localhost:5173 to see the app running.

Development Workflow ​

Branching Strategy ​

  • main: Production-ready code
  • develop: Optional integration branch when team workflow requires it
  • feature/your-feature-name: Your feature branches
  • fix/bug-description: Bug fix branches

Creating a Branch ​

bash
# Update your local main
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/add-new-ai-model

Making Changes ​

  1. Write code following our coding standards
  2. Test your changes locally
  3. Commit frequently with clear messages
  4. Push to your fork:
    bash
    git push origin feature/add-new-ai-model

Keeping Your Branch Updated ​

bash
# Fetch latest changes from upstream
git fetch upstream

# Rebase your branch on upstream/main
git rebase upstream/main

# Force push to your fork (if already pushed)
git push origin feature/add-new-ai-model --force-with-lease

Coding Standards ​

TypeScript ​

  • Use strict mode: All code must pass TypeScript strict checks
  • Explicit types: Avoid any, use specific types or unknown
  • Interfaces over types: Use interface for object shapes
typescript
// Good
interface BlogPost {
  id: string;
  title: string;
  content: string;
  createdAt: Date;
}

function createBlog(data: BlogPost): Promise<BlogPost> {
  // ...
}

// Avoid
function createBlog(data: any) { // ❌ any
  // ...
}

React Components ​

  • Functional components: Use hooks, not class components
  • Named exports: Prefer named over default exports
  • Props interface: Define props interface explicitly
typescript
// Good
interface BlogEditorProps {
  blog: Blog;
  onSave: (blog: Blog) => void;
}

export function BlogEditor({ blog, onSave }: BlogEditorProps) {
  // ...
}

// Avoid
export default function BlogEditor(props) { // ❌ default export, no types
  // ...
}

Naming Conventions ​

  • Components: PascalCase (BlogEditor, SocialPostCard)
  • Functions: camelCase (generateBlogPost, validateInput)
  • Constants: UPPER_SNAKE_CASE (MAX_POSTS_PER_DAY)
  • Files: Match component name (BlogEditor.tsx)

Code Organization ​

  • One component per file (except small, closely related components)
  • Group related functionality (e.g., all brand-related services in brandService.ts)
  • Keep files < 300 lines (split if larger)

Comments ​

  • Use JSDoc for public APIs:
    typescript
    /**
 * Generates an AI-powered blog post based on a topic and brand profile.
 * 
 * @param topic - The blog post topic
 * @param brand - Brand profile for voice and style
 * @returns Generated blog post with frontmatter
 */
export async function generateBlogPost(topic: string, brand: Brand): Promise<BlogPost> {
  // ...
}
  • Explain "why", not "what": Code should be self-documenting; comments explain reasoning

Error Handling ​

typescript
// Good: Specific error handling
try {
  const result = await geminiService.generateContent(prompt);
  return result;
} catch (error) {
  if (error instanceof qaz_RateLimitError) {
    logger.warn('Rate limit hit', { userId });
    throw new qaz_AppError('Please try again in a few minutes', { statusCode: 429 });
  }
  logger.error('Content generation failed', { error, prompt });
  throw new qaz_AppError('Failed to generate content', { statusCode: 500 });
}

// Avoid: Silent failures
try {
  await doSomething();
} catch (error) {
  // ❌ Silent failure
}

Submitting Changes ​

Pull Request Process ​

  1. Ensure your code:

    • Passes TypeScript checks: pnpm build
    • Passes linting: pnpm lint
    • Has no console errors

  2. Create a Pull Request:

    • Go to your fork on GitHub
    • Click "New Pull Request"
    • Select base: main and compare: your-feature-branch
    • Fill in the PR template

  3. PR Title Format:

    feat: Add support for Instagram Reels
fix: Resolve blog editor crash on empty content
docs: Update deployment guide
refactor: Optimize Gemini API calls

    Prefixes:

    • feat: New feature
    • fix: Bug fix
    • docs: Documentation
    • refactor: Code improvement (no behavior change)
    • test: Adding tests
    • chore: Tooling, dependencies

  4. PR Description Template:

    markdown
    ## What does this PR do?
Brief description of changes.

## Why is this change needed?
Explain the problem this solves or feature it adds.

## How was this tested?
- [ ] Tested locally
- [ ] Added unit tests (if applicable)
- [ ] Verified in different browsers

## Screenshots (if UI change)
[Add screenshots here]

## Related Issues
Closes #123

Review Process ​

  • Maintainers will review within 1-3 business days
  • Address feedback by pushing new commits to your branch
  • Once approved, maintainers will merge
  • Celebrate! 🎉 You're now a contributor

Issue Guidelines ​

Before Creating an Issue ​

  1. Search existing issues to avoid duplicates
  2. Check documentation in /docs folder
  3. Try the latest version (main branch)

Bug Reports ​

Use this template:

markdown
**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
- OS: [e.g. Windows 11, macOS 14]
- Browser: [e.g. Chrome 120, Firefox 121]
- Version: [e.g. commit hash or version number]

**Additional context**
Any other context about the problem.

Feature Requests ​

Use this template:

markdown
**Is your feature request related to a problem?**
Describe the problem you're trying to solve.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Other solutions you've thought about.

**Additional context**
Mockups, examples from other tools, etc.

Feature Requests ​

We welcome feature ideas! Here's how to propose them:

  1. Open a GitHub Discussion (not an issue) in the "Ideas" category
  2. Describe the use case: Who would benefit? How would they use it?
  3. Provide examples: Screenshots, mockups, or links to similar features
  4. Engage with feedback: Discuss with the community

Popular features get prioritized (via upvotes and discussion).

Community ​

Where to Get Help ​

  • GitHub Discussions: Ask questions, share ideas
  • GitHub Issues: Report bugs, request features
  • Discord: Real-time chat with community (if enabled for the repo)

Ways to Contribute (Beyond Code) ​

  • Documentation: Improve guides, fix typos, add examples
  • Testing: Test beta features and report bugs
  • Design: Suggest UI/UX improvements
  • Content: Write blog posts, tutorials, or videos
  • Community: Help others in Discussions

Development Tips ​

Debugging ​

bash
# Frontend debugging
# Add debugger statements in code
# Use React DevTools browser extension

# Backend debugging
# Add breakpoints in VS Code
# Or use console.log (temporarily)

Database Changes & Seeding ​

bash
# After modifying apps/backend/prisma/schema.prisma
pnpm db:migrate
pnpm db:generate

# Or push schema changes directly in local development
pnpm db:push

# Seed base application setup data (e.g. system settings, seed company, base credentials)
pnpm db:seed

# Seed comprehensive demo data (mock blogs, scheduled/growing/bloom posts, etc.)
pnpm db:seed:demo

# Seed 90 days of social account analytics mock data (impressions, follower growth, best posting times heatmap)
pnpm db:seed:analytics

Testing ​

bash
# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

Building for Production ​

bash
# Build all apps
pnpm build

License ​

By contributing to TendSocial, you agree that your contributions will be licensed under the MIT License.

Questions? ​

If you have questions not covered here:

Thank you for contributing! 🚀

TendSocial Documentation

Copyright © 2024-2025 TendSocial LLC