Contributing Guide

Welcome Contributors

Utopia Fleet Builder is an open-source project maintained by the Star Trek Attack Wing community. We welcome contributions of all kinds!

Bug Reports

Found an issue? Let us know!

New Features

Have an idea? We’d love to hear it!

Data Updates

Add new ships, captains, or upgrades

Documentation

Help improve the docs

Project Information

Repository: github.com/AngryTribble/Star-Trek-Attack-Wing-Utopia
License: LGPL-3.0
Issue Tracker: GitHub Issues
Homepage: Utopia Fleet Builder

Project Team

Original Author: ComaToesContributors: KFNEXUS, jsterner73, CrazyVulcan, wiegeabo, SpinStabilized, catsgotmytongue, AngryTribble, Relequestual

How to Contribute

Set Up Your Environment

Follow the development setup guide to get started:

git clone https://github.com/AngryTribble/Star-Trek-Attack-Wing-Utopia.git
cd Star-Trek-Attack-Wing-Utopia
npm install
npm start

Create a Branch

Create a new branch for your changes:

git checkout -b feature/my-new-feature
# or
git checkout -b fix/bug-description

Branch naming conventions:

feature/ - New features or enhancements
fix/ - Bug fixes
data/ - Game data additions or corrections
docs/ - Documentation improvements

Make Your Changes

Edit the relevant files:

Code changes in src/js/
Style changes in src/css/
Data changes in src/data/
Template changes in src/templates/

Use watch mode for live rebuilding:

npm run watch

Test Your Changes

Ensure everything works:

npm run build
npm run serve

Open http://localhost:8000 and verify:

New features work as expected
Existing functionality still works
No console errors
UI displays correctly

Commit Your Changes

Write clear, descriptive commit messages:

git add .
git commit -m "Add Sovereign-class ships from Wave 16"

Good commit messages:

“Fix fleet cost calculation for admiral upgrades”
“Add missing Romulan ships from expansion 72015”
“Update build process to support newer Node versions”
“Improve mobile responsiveness of fleet list”

Push and Create Pull Request

Push your branch and create a PR:

git push origin feature/my-new-feature

Then visit GitHub and click “Create Pull Request”.

Contribution Types

Adding Game Data

The most common contribution is adding or correcting game data.

Adding Ships

File: src/data/ships.js

Find an existing ship to use as a template
Copy and modify with the new ship’s details
Assign a unique ID (e.g., S500)
Include all properties: name, class, stats, abilities
Reference the correct expansion set ID

{
  type: "ship",
  id: "S500",
  gameId: 1,
  set: ["75020"],
  name: "I.K.S. Bortas",
  class: "Vor'cha Class",
  actions: ["target-lock", "scan", "battlestations"],
  upgrades: ["weapon", "weapon", "crew", "tech"],
  attack: 4,
  agility: 1,
  hull: 5,
  shields: 4,
  cost: 26,
  text: "Ship ability text here",
  unique: true,
  factions: ["klingon"]
}

Run npm run data to validate and generate.

Adding Captains

File: src/data/captains.jsCaptain cards follow a similar structure:

{
  type: "captain",
  id: "C200",
  gameId: 1,
  set: ["75020"],
  name: "Gowron",
  skill: 7,
  talent: 2,
  cost: 5,
  text: "Captain ability text",
  unique: true,
  factions: ["klingon"]
}

Adding Upgrades

File: src/data/upgrades.jsUpgrade cards include weapon stats if applicable:

{
  type: "upgrade",
  upgradeType: "weapon",
  id: "U700",
  gameId: 1,
  set: ["75020"],
  name: "Disruptor Cannons",
  attack: 4,
  range: "1-2",
  cost: 5,
  text: "Weapon ability text",
  unique: false,
  factions: ["klingon", "romulan"]
}

Adding Expansion Sets

File: src/data/sets.jsRegister new expansion sets:

{
  id: "75020",
  name: "I.K.S. Bortas Expansion",
  wave: "Wave 20",
  releaseDate: "2016-03-01",
  type: "expansion"
}

Code Contributions

JavaScript Guidelines

Follow existing code style and conventions
Use clear, descriptive variable names
Comment complex logic
Test in multiple browsers
Maintain AngularJS patterns (controllers, services, directives)

AngularJS version: The project uses AngularJS 1.x (not Angular 2+)

CSS Guidelines

Maintain consistent naming conventions
Avoid overly specific selectors
Test responsive layouts on mobile devices
Use existing color variables and styles
Consider print stylesheet if relevant

HTML Templates

Keep templates focused and modular
Use AngularJS directives appropriately
Ensure accessibility (alt text, ARIA labels)
Test with screen readers if possible

Bug Fixes

Identify the Issue

Reproduce the bug and understand its scope:

What triggers it?
What’s the expected behavior?
What actually happens?

Find the Cause

Use browser dev tools to debug:

Check console for errors
Use source maps to trace minified code
Test with different data inputs

Implement the Fix

Make minimal changes to fix the issue:

Don’t refactor unrelated code
Add comments explaining the fix
Consider edge cases

Test Thoroughly

Verify the fix works:

Test the specific bug scenario
Test related functionality
Check for regressions

Pull Request Guidelines

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Data update
- [ ] Documentation
- [ ] Code refactoring

## Changes Made
- Detailed list of changes
- What was added/modified/removed

## Testing
How was this tested?
- [ ] Local build and serve
- [ ] Browser testing (Chrome/Firefox/Safari)
- [ ] Mobile testing

## Screenshots (if applicable)
Add screenshots for UI changes

## Related Issues
Fixes #123
Related to #456

PR Checklist

Before submitting your PR:

Code builds without errors (npm run build)
No ESLint errors in data files (npm run lint-data)
Changes tested locally
Commit messages are clear and descriptive
PR description explains the changes
No unnecessary files committed (node_modules, build outputs)

Never commit files in staw-utopia/ directory. These are generated files and should not be in version control.

Code Review Process

Submission: You create a pull request
Review: Maintainers review your changes
Feedback: You may receive comments or change requests
Updates: Make requested changes and push updates
Approval: Once approved, your PR will be merged
Merge: Your changes become part of the project

Be patient during review. Maintainers are volunteers and may take time to respond.

Reporting Issues

Bug Reports

When reporting bugs, include:

Description: What went wrong?
Steps to Reproduce: How to trigger the bug
Expected Behavior: What should happen
Actual Behavior: What actually happens
Environment: Browser, OS, device
Screenshots: If applicable
Console Errors: Any JavaScript errors

Example:

**Bug:** Fleet cost calculation incorrect with Admiral upgrades

**Steps:**
1. Create a new fleet
2. Add a ship with Admiral upgrade slot
3. Add Admiral Janeway (cost 4)
4. Observe total fleet cost

**Expected:** Cost should increase by 4
**Actual:** Cost increases by 8

**Browser:** Chrome 120.0 on Windows 11
**Console:** "TypeError: Cannot read property 'cost' of undefined"

Feature Requests

For feature requests, describe:

Problem: What limitation exists?
Solution: How would the feature help?
Alternatives: Other ways to solve it?
Use Case: When would you use this?

Style Guidelines

Code Formatting

// Use camelCase for variables and functions
var myVariable = "value";
function calculateFleetCost() { ... }

// Use descriptive names
var totalCost = 0;  // Good
var tc = 0;         // Avoid

// Add comments for complex logic
// Calculate total including faction penalties
if (isCrossFaction) {
  totalCost += penaltyCost;
}

Data Formatting

Data Entries

module.exports = [
  {
    type: "ship",
    id: "S001",
    name: "Ship Name",
    // Alphabetize properties for consistency
    actions: [...],
    attack: 5,
    class: "Class Name",
    cost: 30,
    factions: [...],
    // etc.
  },
  // Use consistent indentation (2 spaces)
];

Community Guidelines

Be Respectful: Treat all contributors with respect
Be Patient: Everyone is learning
Be Constructive: Offer helpful feedback
Be Collaborative: Work together toward solutions
Be Inclusive: Welcome newcomers

This is a community project. We’re all Star Trek Attack Wing fans working together to build the best fleet builder possible.

Getting Help

If you need assistance:

Check the documentation - Most questions are answered here
Search existing issues - Someone may have had the same problem
Ask in issues - Create an issue with your question
Be specific - Provide details and context

Recognition

All contributors are acknowledged in:

package.json contributors list
GitHub contributor graph
Project README

Thank you for contributing to Utopia Fleet Builder!

Next Steps

Development Setup

Set up your local environment

Data Structure

Learn how data is organized

Build Process

Understand the build system

GitHub Issues

View open issues

Get Started

User Guide

Game Data

Development

Welcome Contributors

Bug Reports

New Features

Data Updates

Documentation

Project Information

Project Team

How to Contribute

Contribution Types

Adding Game Data

Code Contributions

Bug Fixes

Pull Request Guidelines

PR Description Template

PR Checklist

Code Review Process

Reporting Issues

Bug Reports

Feature Requests

Style Guidelines

Code Formatting

Data Formatting

Community Guidelines

Getting Help

Recognition

Next Steps

Development Setup

Data Structure

Build Process

GitHub Issues

Build docs developers (and LLMs) love

Get Started

User Guide

Game Data

Development

​Welcome Contributors

Bug Reports

New Features

Data Updates

Documentation

​Project Information

​Project Team

​How to Contribute

​Contribution Types

​Adding Game Data

​Code Contributions

​Bug Fixes

​Pull Request Guidelines

​PR Description Template

​PR Checklist

​Code Review Process

​Reporting Issues

​Bug Reports

​Feature Requests

​Style Guidelines

​Code Formatting

​Data Formatting

​Community Guidelines

​Getting Help

​Recognition

​Next Steps

Development Setup

Data Structure

Build Process

GitHub Issues

Build docs developers (and LLMs) love

Welcome Contributors

Project Information

Project Team

How to Contribute

Contribution Types

Adding Game Data

Code Contributions

Bug Fixes

Pull Request Guidelines

PR Description Template

PR Checklist

Code Review Process

Reporting Issues

Bug Reports

Feature Requests

Style Guidelines

Code Formatting

Data Formatting

Community Guidelines

Getting Help

Recognition

Next Steps