FELgt Contribution Guide - First Time Contributor

🎯 Overview

This guide will walk you through contributing TypeScript code generation to the FELgt repository. Don't worry if you've never contributed to open source before - this guide covers everything step by step!

📋 Prerequisites

Required Tools

Git - Version control

# Check if installed
git --version

# If not installed, download from:
# https://git-scm.com/downloads

GitHub Account
- Sign up at: https://github.com
- Verify your email

Node.js & npm (for TypeScript development)

# Check if installed
node --version
npm --version

# If not installed, download from:
# https://nodejs.org/

Code Editor
- VS Code (recommended): https://code.visualstudio.com/
- Or any editor you prefer

🚀 Step-by-Step Contribution Process

Step 1: Fork the Repository

What is forking?

Creates your own copy of the repository
You can make changes without affecting the original
You can submit changes back via Pull Request

How to Fork:

Go to the repository:
- Visit: https://github.com/krudos/FELgt
Click the "Fork" button:
- Top right corner of the page
- This creates https://github.com/YOUR_USERNAME/FELgt
Wait for fork to complete:
- GitHub will redirect you to your fork
- You now have your own copy!

Step 2: Clone Your Fork

What is cloning?

Downloads the repository to your computer
Creates a local copy you can edit

How to Clone:

Get your fork's URL:
- On your fork's page, click the green "Code" button
- Copy the HTTPS URL (e.g., https://github.com/YOUR_USERNAME/FELgt.git)
Open Terminal/Command Prompt:
- On Mac: Terminal app
- On Windows: Command Prompt or PowerShell
- On Linux: Terminal

Navigate to where you want the project:

cd ~/projects  # or wherever you keep projects

Clone the repository:

git clone https://github.com/YOUR_USERNAME/FELgt.git
cd FELgt

Verify it worked:
```
ls  # Should show repository files
```

Step 3: Set Up Remote Tracking

Why?

Keeps your fork in sync with the original repository
Allows you to pull updates from the original

How to Set Up:

Add the original repository as "upstream":

git remote add upstream https://github.com/krudos/FELgt.git

Verify remotes:

git remote -v
# Should show:
# origin    https://github.com/YOUR_USERNAME/FELgt.git (fetch)
# origin    https://github.com/YOUR_USERNAME/FELgt.git (push)
# upstream  https://github.com/krudos/FELgt.git (fetch)
# upstream  https://github.com/krudos/FELgt.git (push)

Step 4: Explore the Repository

Understand the structure:

# List all files
ls -la

# Check if there's a README
cat README.md

# Look at the directory structure
tree  # or: find . -type f -name "*.cs" | head -20

Key things to find:

How does C# generation work?
What's the project structure?
Are there tests?
What's the build process?

Read the code:

Open the project in your code editor
Look for the C# generator implementation
Understand the pattern

Step 5: Create a Feature Branch

Why use branches?

Keeps your changes organized
Allows multiple features in parallel
Easy to switch between work

How to Create:

Make sure you're on main/master:

git checkout main
# or
git checkout master

Pull latest changes:

git pull upstream main
# or
git pull upstream master

Create a new branch:

git checkout -b feature/typescript-generator

Verify you're on the new branch:

git branch
# Should show * feature/typescript-generator

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation
refactor/ - Code refactoring

Step 6: Understand the Existing Code

Before writing TypeScript generator, understand C# generator:

Find the C# generator:

find . -name "*generator*" -o -name "*Generator*"

Read the code:
- How does it parse XSD?
- How does it generate C# classes?
- What's the architecture?

Run the existing generator:

# Check for build instructions
cat README.md

# Or look for build files
ls *.sln *.csproj  # C# project files

Test the existing functionality:
- Make sure you understand how it works
- Run tests if they exist
- Generate C# code to see output

Step 7: Implement TypeScript Generator

Create the TypeScript generator following the C# pattern:

Create directory structure:
```
mkdir -p src/Generators/TypeScript
```

Create TypeScript generator class:

// src/Generators/TypeScript/TypeScriptGenerator.cs
namespace FELgt.Generators.TypeScript
{
    public class TypeScriptGenerator : IGenerator
    {
        public string Generate(XSDModel model)
        {
            // Implementation here
        }
    }
}

Follow the existing pattern:
- Look at how C# generator is structured
- Mirror the same architecture
- Reuse XSD parser if possible
Implement step by step:
- Start with simple types
- Add interfaces
- Handle namespaces
- Add enums
- Handle optional/required fields

Step 8: Test Your Implementation

Create tests:

Find existing tests:
```
find . -name "*test*" -o -name "*Test*"
```
Create TypeScript generator tests:
- Test with sample XSD files
- Verify output is valid TypeScript
- Check type correctness

Test manually:

# Run your generator
dotnet run -- --lang typescript --input test.xsd --output output/

# Check output
cat output/typescript/*.ts

Validate TypeScript:

# Install TypeScript compiler
npm install -g typescript

# Check if generated code compiles
tsc --noEmit output/typescript/*.ts

Step 9: Update Documentation

Update README.md:

Add TypeScript section:

## TypeScript Generation

Generate TypeScript interfaces from XSD:

```bash
dotnet run -- --lang typescript --input xsd/ --output output/typescript/

Add examples:
- Show input XSD
- Show generated TypeScript
- Show usage example
Update usage instructions:
- Add TypeScript to language options
- Update examples

Step 10: Commit Your Changes

Git commit workflow:

Check what changed:

git status
# Shows modified, new, and deleted files

Stage your changes:

# Add specific files
git add src/Generators/TypeScript/TypeScriptGenerator.cs
git add README.md

# Or add all changes
git add .

Commit with a good message:

git commit -m "feat: Add TypeScript code generator

- Implement TypeScriptGenerator class
- Generate TypeScript interfaces from XSD
- Support namespaces and type mapping
- Add tests for TypeScript generation
- Update README with TypeScript examples

Closes #XX"  # Replace XX with issue number if applicable

Commit message best practices:

Use present tense: "Add" not "Added"
First line: Short summary (50 chars)
Blank line
Detailed description
Reference issues: "Closes #123"

Verify commit:

git log --oneline -1
# Should show your commit

Step 11: Keep Your Fork Updated

Before pushing, sync with upstream:

Fetch latest changes:
```
git fetch upstream
```

Merge upstream changes:

git checkout main  # or master
git merge upstream/main

Update your feature branch:

git checkout feature/typescript-generator
git merge main
# Resolve conflicts if any

Push to your fork:

git push origin feature/typescript-generator

Step 12: Create a Pull Request

What is a Pull Request (PR)?

Request to merge your changes into the original repository
Maintainers review your code
They can suggest changes or approve

How to Create a PR:

Go to your fork on GitHub:
- Visit: https://github.com/YOUR_USERNAME/FELgt
You'll see a banner:
- "feature/typescript-generator had recent pushes"
- Click "Compare & pull request"
Or manually:
- Click "Pull requests" tab
- Click "New pull request"
- Select: krudos/FELgt main ← YOUR_USERNAME/FELgt feature/typescript-generator

Fill out the PR form:

Title:

feat: Add TypeScript code generator

Description:

## Description

This PR adds TypeScript code generation support to FELgt, similar to the existing C# generator.

## Changes

- ✅ Implemented `TypeScriptGenerator` class
- ✅ Added TypeScript type mapping from XSD types
- ✅ Support for namespaces and interfaces
- ✅ Added tests for TypeScript generation
- ✅ Updated README with TypeScript examples

## Testing

- [x] Generated TypeScript from sample XSD files
- [x] Verified TypeScript compiles without errors
- [x] Tested with FACT, NCRE, NDEB, ANULACION schemas

## Screenshots/Examples

```typescript
// Generated TypeScript interface
export interface DatosGenerales {
  Tipo: 'FACT' | 'NCRE' | 'NDEB';
  FechaHoraEmision: string;
  CodigoMoneda: string;
}

Closes #XX # If there's an issue

Click "Create pull request"

Step 13: Respond to Feedback

What happens next:

Maintainers review your code:
- They may ask questions
- They may suggest changes
- They may approve

If changes requested:

# Make the changes
# ... edit files ...

# Commit the fixes
git add .
git commit -m "fix: Address review feedback

- Fix type mapping for dateTime
- Add missing namespace handling
- Update documentation"

# Push to same branch
git push origin feature/typescript-generator

PR updates automatically
Maintainers get notified

If approved:
- Maintainer merges your PR
- Your code is now in the main repository!
- 🎉 Congratulations!

🎯 Best Practices

Code Quality

Follow existing patterns:
- Match the C# generator structure
- Use same naming conventions
- Follow project style
Write clean code:
- Add comments where needed
- Use meaningful variable names
- Keep functions focused
Add tests:
- Test your generator
- Test edge cases
- Ensure backward compatibility

Communication

Be respectful:
- Maintainers are volunteers
- Be patient with responses
- Accept feedback gracefully
Be clear:
- Explain your changes
- Answer questions thoroughly
- Update PR description if needed
Be responsive:
- Check for comments regularly
- Respond to feedback promptly
- Keep the conversation going

Git Workflow

Keep commits focused:
- One feature per commit
- Logical grouping
- Clear commit messages
Keep branch clean:
- Don't mix unrelated changes
- Rebase if needed (ask first)
- Keep history readable
Sync regularly:
- Pull upstream changes
- Resolve conflicts early
- Keep your fork updated

🐛 Common Issues & Solutions

Issue: "Permission denied"

Solution:

# Check your Git config
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# If using SSH, set up SSH keys:
# https://docs.github.com/en/authentication/connecting-to-github-with-ssh

Issue: Merge conflicts

Solution:

# When merging upstream changes
git merge upstream/main
# If conflicts:
# 1. Open conflicted files
# 2. Look for <<<<<< markers
# 3. Resolve conflicts manually
# 4. git add .
# 5. git commit

Issue: PR shows wrong changes

Solution:

# Make sure you're on the right branch
git branch

# Make sure you pushed the right branch
git push origin feature/typescript-generator

# Check what's in your branch
git log --oneline

Issue: Can't push to fork

Solution:

# Check remote URL
git remote -v

# If wrong, update it:
git remote set-url origin https://github.com/YOUR_USERNAME/FELgt.git

# Try pushing again
git push origin feature/typescript-generator

📚 Learning Resources

✅ Pre-PR Checklist

Before submitting your PR, make sure:

🎉 After Your PR is Merged

Celebrate! 🎊

Your code is now in the main repository
You've helped the FEL community
You can reference this in your portfolio

Next steps:

Keep your fork updated
Help others with their PRs
Continue contributing!

🆘 Getting Help

If you get stuck:

Check documentation:
- Repository README
- GitHub issues
- Project wiki
Ask for help:
- Open an issue on the repository
- Ask in PR comments
- Reach out to maintainers
Community:
- GitHub Discussions (if enabled)
- Stack Overflow (tag: fel-guatemala)
- FEL developer communities

Last Updated: 2025-12-18
Status: Complete Guide - Ready to Use!

🎯 Overview​

📋 Prerequisites​

Required Tools​

🚀 Step-by-Step Contribution Process​

Step 1: Fork the Repository​

Step 2: Clone Your Fork​

Step 3: Set Up Remote Tracking​

Step 4: Explore the Repository​

Step 5: Create a Feature Branch​

Step 6: Understand the Existing Code​

Step 7: Implement TypeScript Generator​

Step 8: Test Your Implementation​

Step 9: Update Documentation​

Step 10: Commit Your Changes​

Step 11: Keep Your Fork Updated​

Step 12: Create a Pull Request​

Related Issues​

Step 13: Respond to Feedback​

🎯 Best Practices​

Code Quality​

Communication​

Git Workflow​

🐛 Common Issues & Solutions​

Issue: "Permission denied"​

Issue: Merge conflicts​

Issue: PR shows wrong changes​

Issue: Can't push to fork​

📚 Learning Resources​

Git & GitHub​

Open Source Contribution​

C# Development (for this project)​

✅ Pre-PR Checklist​

🎉 After Your PR is Merged​

🆘 Getting Help​

🎯 Overview

📋 Prerequisites

Required Tools

🚀 Step-by-Step Contribution Process

Step 1: Fork the Repository

Step 2: Clone Your Fork

Step 3: Set Up Remote Tracking

Step 4: Explore the Repository

Step 5: Create a Feature Branch

Step 6: Understand the Existing Code

Step 7: Implement TypeScript Generator

Step 8: Test Your Implementation

Step 9: Update Documentation

Step 10: Commit Your Changes

Step 11: Keep Your Fork Updated

Step 12: Create a Pull Request

Related Issues

Step 13: Respond to Feedback

🎯 Best Practices

Code Quality

Communication

Git Workflow

🐛 Common Issues & Solutions

Issue: "Permission denied"

Issue: Merge conflicts

Issue: PR shows wrong changes

Issue: Can't push to fork

📚 Learning Resources

Git & GitHub

Open Source Contribution

C# Development (for this project)

✅ Pre-PR Checklist

🎉 After Your PR is Merged

🆘 Getting Help