Project Guidelines

Why These Guidelines Matter

Good project structure and workflow practices aren’t just bureaucracy—they’re what separate chaotic solo projects from professional collaborative work. When everyone follows the same patterns, it’s easier to jump between projects, onboard new contributors, and maintain code over time.

These guidelines are based on industry standards and our collective experience. They’re not meant to stifle creativity, but to give you a solid foundation so you can focus on building cool stuff instead of figuring out where files should go.

Remember: These are guidelines, not rigid laws. If your project has a good reason to deviate, that’s fine—just document why in your README so others understand your choices.

1. Starting a New Project

Before You Begin

Ask yourself:

• Does this project align with SEAD Club’s goals and values?
• Are you willing to maintain it or find maintainers?
• Would others in the club benefit from or want to contribute to this?
• Is there already a similar project you could contribute to instead?

If you’re unsure, pitch your idea in our community channels first. You might find collaborators or get feedback that shapes the project in useful ways.

Project Setup Checklist

When creating a new project, include these from the start:

Essential Files:

• README.md – What the project is, how to set it up, how to use it (see below for details)
• LICENSE – Pick a license (MIT and Apache 2.0 are common for open source)
• .gitignore – Prevent committing unnecessary files (node_modules, .env, build artifacts, etc.)
• Contributing guidelines – Either a CONTRIBUTING.md file or a section in the README

For Most Projects:

• Package/dependency file – package.json, requirements.txt, Cargo.toml, etc.
• Configuration files – .env.example (never commit actual .env with secrets!), config templates
• .github/ISSUE_TEMPLATE/ – Templates for bug reports and feature requests (optional but helpful)

Writing a Good README

Your README is the first thing people see. A good README includes:

# Project Name

Brief description of what this project does (1-2 sentences).

## What It Does

A bit more detail about the project's purpose and main features.

## Setup

### Prerequisites
- Node.js 18+
- PostgreSQL 14+
- Whatever else you need

### Installation
1. Clone the repo: `git clone ...`
2. Install dependencies: `npm install`
3. Copy `.env.example` to `.env` and fill in values
4. Run migrations: `npm run migrate`
5. Start the server: `npm start`

## Usage

Basic examples of how to use the project.

## Contributing

See our [Contributing Guide](link) or check out issues tagged "good first issue."

## License

[Your chosen license]

Don’t just copy this template blindly—adapt it to your project. The goal is to get someone from zero to running the project in under 10 minutes.

2. Project Structure

Consistent structure makes projects easier to navigate. Here are common patterns:

General Structure

project-name/
├── README.md
├── LICENSE
├── .gitignore
├── docs/              # Documentation beyond the README
├── src/               # Source code
│   ├── main.ext       # Entry point
│   ├── components/    # Reusable components
│   ├── utils/         # Helper functions
│   └── ...
├── tests/             # Test files
├── assets/            # Images, fonts, static files
├── config/            # Configuration files
└── scripts/           # Build scripts, utilities

Language-Specific Patterns

JavaScript/TypeScript (Web):

project/
├── src/
│   ├── components/
│   ├── pages/
│   ├── hooks/
│   ├── utils/
│   └── styles/
├── public/
├── package.json
└── ...

Python:

project/
├── src/
│   └── project_name/
│       ├── __init__.py
│       ├── main.py
│       └── modules/
├── tests/
├── requirements.txt
└── ...

Rust:

project/
├── src/
│   ├── main.rs
│   ├── lib.rs
│   └── modules/
├── Cargo.toml
└── ...

The key principle: Related code lives together, and the structure is intuitive. If someone opens your repo, they should be able to guess where things are without reading documentation.

Documentation Directory

If your project needs more docs than a README:

docs/
├── getting-started.md
├── api-reference.md
├── architecture.md
└── deployment.md

Keep it organized and cross-link documents. Consider using a tool like MkDocs, Docusaurus, or even just GitHub’s wiki feature for larger projects.

3. Version Control Best Practices

We use Git for all projects. If you’re new to Git, that’s fine—you’ll learn by doing. Here’s how we use it effectively:

Branching Strategy

Main branch: Always stable and deployable

• Never commit directly to main
• All changes come through pull requests

Feature branches: For new features, bug fixes, or experiments

# Create a descriptive branch name
git checkout -b feature/add-user-auth
git checkout -b fix/login-redirect-bug
git checkout -b docs/update-readme

Branch naming conventions:

• feature/description – New features
• fix/description – Bug fixes
• docs/description – Documentation changes
• refactor/description – Code refactoring
• test/description – Adding or updating tests

Keep branch names short but descriptive. fix/bug is too vague; fix/navbar-mobile-overflow tells you exactly what it addresses.

Commit Messages

Write commits that explain what changed and why.

Bad commits:

- "fixed stuff"
- "update"
- "changes"
- "asdfasdf"

Good commits:

- "Add user authentication with JWT"
- "Fix navbar overflow on mobile devices"
- "Refactor database connection to use connection pooling"
- "Update README with new API endpoints"

Format:

Short summary (50 chars or less)

More detailed explanation if needed. Explain what and why,
not how (the code shows how). Wrap at 72 characters.

- Bullet points are fine
- Reference issues: Fixes #123

For small, obvious changes, a one-line commit is fine. For complex changes, add context in the description.

Pull Requests

Before merging any code into main, open a pull request (PR).

When creating a PR:

1. Give it a clear title describing the change
2. Fill out the description:
   • What does this change do?
   • Why is it needed?
   • How has it been tested?
   • Any breaking changes or special deployment notes?
3. Link related issues (e.g., “Closes #42”)
4. Request reviews from relevant people
5. Be responsive to feedback

When reviewing a PR:

• Test the code locally if possible
• Check for bugs, edge cases, and potential issues
• Suggest improvements constructively
• Approve if it looks good, or request changes with clear explanations
• Remember: you’re reviewing code, not judging the person

Merging:

• Squash small fixup commits before merging
• Use “Squash and merge” for feature branches with messy history
• Use “Merge commit” for larger features you want to preserve history
• Delete the branch after merging (GitHub can do this automatically)

Version Tags

Tag releases so people can reference specific versions:

# Semantic versioning: MAJOR.MINOR.PATCH
git tag -a v1.0.0 -m "Initial stable release"
git push origin v1.0.0

See our Versioning Conventions for more details on when to bump version numbers.

4. Collaboration Practices

Projects succeed when people work well together. Here’s how we collaborate effectively:

Communication

Use the right channel:

• Telegram/Discord – Quick questions, casual discussion, general help
• GitHub Issues – Bug reports, feature requests, task tracking
• Pull Request comments – Code-specific discussions
• Project meetings – Big decisions, planning, architecture discussions

Be responsive but realistic:

• Don’t expect immediate responses—people have classes and lives
• If you can’t work on something, say so instead of going silent
• Update issues/PRs with your progress or blockers

GitHub Issues

Issues are how we track work. Create issues for:

• Bugs you’ve found
• Features you want to add
• Questions about the project
• Tasks that need doing

Writing good issues:

For bugs:

**Description:** Login button doesn't work on Safari

**Steps to reproduce:**
1. Go to /login
2. Enter valid credentials
3. Click "Login"
4. Nothing happens

**Expected:** User should be logged in
**Actual:** Button does nothing, no error shown

**Environment:** Safari 17.2, macOS 14.1

For features:

**Problem:** Users can't reset their passwords

**Proposed solution:** Add a "Forgot Password" flow with email verification

**Details:**
- Add link on login page
- Send reset email with temporary token
- Create reset password form
- Token expires after 1 hour

**Why this matters:** Users currently have to contact admins, creating support burden

Use labels (bug, enhancement, documentation, good first issue, etc.) to categorize issues.

Code Reviews

Code review is a learning opportunity for everyone involved.

As the author:

• Make PRs small and focused (one feature/fix per PR)
• Explain your approach in the description
• Don’t take feedback personally
• Ask questions if you don’t understand suggestions

As the reviewer:

• Be kind and constructive
• Explain why something should change, not just that it should
• Acknowledge good work: “Nice approach here!”
• Distinguish between “must fix” and “nice to have” suggestions
• Remember the author is learning (and so are you)

Example review comments:

❌ “This is wrong” ✅ “This could cause issues when X happens. Consider handling that case with…”

❌ “Why did you do it this way?” ✅ “I’m curious about this approach. Have you considered [alternative]? It might simplify things because…”

❌ “Just use a library” ✅ “There’s a library (link) that handles this well and has good documentation. Might save reinventing the wheel?”

Project Ownership and Maintenance

Project maintainers:

• Keep the project moving forward
• Review and merge PRs in a reasonable timeframe
• Triage issues and close stale ones
• Make architectural decisions
• Onboard new contributors

If you start a project, you’re committing to maintain it (or find someone who will). If you can’t maintain it anymore, be upfront about it. We can find new maintainers or archive the project rather than letting it rot.

Shared projects: For club-wide projects, maintainership is shared. Major decisions should involve multiple people, and no one person should be a single point of failure.

5. Code Quality Standards

We want code that works, is readable, and can be maintained by others.

General Principles

• Write for humans first – Code is read more than written
• Keep it simple – The simplest solution that works is usually best
• Don’t repeat yourself – Extract repeated code into functions
• Test your code – At minimum, manually test edge cases
• Comment the “why,” not the “what” – Code shows what, comments explain why

Testing

We encourage tests, especially for:

• Critical functionality (auth, payments, data handling)
• Bug fixes (write a test that would have caught the bug)
• Complex logic (algorithms, business rules)

You don’t need 100% test coverage, but test the important stuff. See individual projects for their testing setup.

Dependencies

Before adding a dependency:

• Is it well-maintained?
• Is it necessary, or could you implement it yourself quickly?
• Does it have known security issues?
• Will it bloat the project?

Update dependencies regularly but test after updates. Use tools like Dependabot to catch security vulnerabilities.

6. Documentation

Good documentation saves everyone time. Document:

In code:

• Complex algorithms or business logic
• Non-obvious design decisions
• TODOs with context (and ideally an issue link)

In README:

• How to set up and run the project
• Basic usage examples
• How to contribute

In separate docs (if needed):

• API documentation
• Architecture decisions
• Deployment procedures
• Troubleshooting guides

Keep docs up to date. Outdated docs are worse than no docs because they mislead people.

7. Security and Privacy

Never commit:

• API keys, passwords, or secrets (use .env files and .gitignore)
• Personal data or user information
• Proprietary code you don’t have permission to share

If you accidentally commit a secret:

1. Immediately revoke/regenerate it
2. Remove it from Git history (git filter-branch or BFG)
3. Force push the cleaned history
4. Notify maintainers

Consider security in your code:

• Validate user input
• Use parameterized queries to prevent SQL injection
• Hash passwords, never store them plaintext
• Keep dependencies updated for security patches

8. When Things Go Wrong

Mistakes happen. It’s how you handle them that matters.

If you broke something:

• Don’t panic
• Revert the change if needed (git revert or git reset)
• Figure out what went wrong
• Fix it and document what happened
• Learn from it

If you’re stuck:

• Review these guidelines and the project’s README
• Search for similar issues
• Ask for help with specific questions

If you disagree with a decision:

• Talk to the project maintainers
• Explain your reasoning constructively
• Accept that sometimes you’ll be outvoted—that’s okay

Contributing to These Guidelines

These guidelines evolve based on what actually works for our projects. If you have suggestions:

• Open an issue to discuss changes
• Submit a pull request with your proposed updates
• Bring it up in a club meeting

We want these to be useful, not burdensome. Your feedback helps us improve them.

Remember: These guidelines exist to help you build better projects and collaborate more effectively. They’re not meant to slow you down or make things more complicated. When in doubt, ask. When something doesn’t make sense, question it. We’re all learning together.