Skip to main content

Welcome Contributors

Thank you for your interest in contributing to MatriculaUniPoo! This guide will help you understand how to contribute effectively to the project.
Whether you’re fixing bugs, adding features, improving documentation, or suggesting enhancements, your contributions are valuable and appreciated.

Code of Conduct

Before contributing, please:
  • Be respectful and considerate in all interactions
  • Provide constructive feedback
  • Focus on what is best for the community
  • Show empathy towards other contributors

Getting Started

1

Fork the Repository

Create your own fork of the MatriculaUniPoo repository:
# Click "Fork" on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/Matricula.git
cd Matricula
2

Set Up Development Environment

Follow the Development Setup guide to configure your environment with Java 20 and Maven.
3

Create a Branch

Create a new branch for your changes:
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description
Use descriptive branch names:
  • feature/add-course-search
  • fix/login-validation-bug
  • docs/update-setup-guide
  • refactor/improve-course-model
4

Make Your Changes

Implement your changes following the coding standards outlined below.
5

Test Your Changes

Ensure your changes work correctly:
mvn clean compile
mvn exec:java -Dexec.mainClass="logica.Main"
Test all affected functionality manually or add unit tests.
6

Commit Your Changes

Write clear, descriptive commit messages:
git add .
git commit -m "Add course search functionality"
7

Push and Create Pull Request

git push origin feature/your-feature-name
Then create a Pull Request on GitHub with a detailed description of your changes.

Coding Standards

Java Style Guidelines

Follow these conventions to maintain consistency:
Classes: PascalCase
public class Alumno { }
public class CourseEnrollment { }
Methods and Variables: camelCase
private String nombreCompleto;
public void setNombre(String nombre) { }
Constants: UPPER_SNAKE_CASE
private static final int MAX_COURSES = 5;
private static final String DEFAULT_LANGUAGE = "es";
Packages: lowercase
package logica;
package igu;
Indentation: 4 spaces (no tabs)Braces: K&R style
public void example() {
    if (condition) {
        // code here
    } else {
        // code here
    }
}
Line Length: Maximum 120 charactersImports: Group and sort alphabetically
import java.util.ArrayList;
import javax.swing.JOptionPane;
import logica.Alumno;
import logica.Cursos;
JavaDoc for Public Methods:
/**
 * Registers a new student in the system.
 * 
 * @param nombre Student's first name
 * @param apellido Student's last name
 * @param dni Student's national ID number
 * @param contraseña Student's password
 * @return true if registration successful, false otherwise
 */
public boolean registrarAlumno(String nombre, String apellido, 
                               String dni, String contraseña) {
    // Implementation
}
Inline Comments: Use for complex logic
// Validate that all required fields are filled
if (nombre.isEmpty() || apellido.isEmpty()) {
    return false;
}

Project Structure Guidelines

GUI Package (igu)

Place all Swing UI components here:
  • JFrame classes
  • Form definitions
  • Event handlers
  • UI utility classes

Logic Package (logica)

Place business logic here:
  • Data models (JavaBeans)
  • Validation logic
  • Business rules
  • Main entry point
If adding new packages (e.g., dao for database access, util for utilities), discuss with maintainers first.

Model Classes Pattern

When creating or modifying model classes, follow the JavaBean pattern:
Example Model Class
package logica;

public class Profesor {
    // Private fields
    private String nombre;
    private String apellido;
    private String especialidad;
    private String codigo;
    
    // Default constructor
    public Profesor() {
    }
    
    // Parameterized constructor
    public Profesor(String nombre, String apellido, 
                   String especialidad, String codigo) {
        this.nombre = nombre;
        this.apellido = apellido;
        this.especialidad = especialidad;
        this.codigo = codigo;
    }
    
    // Getters and setters
    public String getNombre() {
        return nombre;
    }
    
    public void setNombre(String nombre) {
        this.nombre = nombre;
    }
    
    public String getApellido() {
        return apellido;
    }
    
    public void setApellido(String apellido) {
        this.apellido = apellido;
    }
    
    // Additional getters/setters...
    
    // Optional: toString() for debugging
    @Override
    public String toString() {
        return "Profesor{" +
               "nombre='" + nombre + '\'' +
               ", apellido='" + apellido + '\'' +
               ", especialidad='" + especialidad + '\'' +
               ", codigo='" + codigo + '\'' +
               '}';
    }
}

GUI Components Pattern

When creating Swing GUI components:

Form Initialization

GUI Best Practices
package igu;

import javax.swing.JFrame;
import logica.Alumno;

public class MiForm extends JFrame {
    // Reference to other forms
    private OtraForm otraForm;
    
    // Data model
    private Alumno alumno;
    
    // Constructor
    public MiForm() {
        initComponents();  // NetBeans-generated UI initialization
        setupCustomComponents();  // Your custom initialization
    }
    
    // Custom initialization method
    private void setupCustomComponents() {
        // Set window properties
        setLocationRelativeTo(null);  // Center on screen
        setResizable(false);
        
        // Initialize data models
        alumno = new Alumno();
    }
    
    // Getters and setters for form references
    public void setOtraForm(OtraForm otraForm) {
        this.otraForm = otraForm;
    }
    
    // NetBeans-generated code
    @SuppressWarnings("unchecked")
    private void initComponents() {
        // Auto-generated by NetBeans Form Designer
    }
}

Event Handlers

Event Handler Pattern
private void btnGuardarActionPerformed(java.awt.event.ActionEvent evt) {
    // 1. Get input from form fields
    String nombre = txtNombre.getText().trim();
    String apellido = txtApellido.getText().trim();
    
    // 2. Validate input
    if (nombre.isEmpty()) {
        JOptionPane.showMessageDialog(this, 
            "Por favor ingrese el nombre",
            "Campo requerido", 
            JOptionPane.WARNING_MESSAGE);
        txtNombre.requestFocus();
        return;
    }
    
    // 3. Process data
    alumno.setNombre(nombre);
    alumno.setApellido(apellido);
    
    // 4. Show confirmation
    JOptionPane.showMessageDialog(this, 
        "Datos guardados exitosamente",
        "Éxito", 
        JOptionPane.INFORMATION_MESSAGE);
    
    // 5. Navigate to next screen if needed
    // siguienteForm.setVisible(true);
    // this.setVisible(false);
}

Input Validation

Always validate user input before processing:
public boolean validarTexto(String texto, String nombreCampo) {
    if (texto == null || texto.trim().isEmpty()) {
        JOptionPane.showMessageDialog(this,
            "El campo " + nombreCampo + " es requerido",
            "Validación",
            JOptionPane.WARNING_MESSAGE);
        return false;
    }
    return true;
}

Common Contribution Areas

Feature Enhancements

Database Integration

Add persistence layer using JDBC or JPA to store student and course data permanently.

Enhanced Validation

Improve input validation, add email validation, password strength checking.

Course Search

Add search and filter functionality for available courses.

Reporting

Generate PDF or Excel reports of enrolled students and courses.

Bug Fixes

Common areas that need attention:
Issue: Image paths are hardcoded to specific Windows directoriesLocation:
  • Inicio.java:52
  • Login.java:140
Solution: Move images to src/main/resources/ and load using:
new ImageIcon(getClass().getResource("/images/background.png"))
Issue: Passwords stored in plain textLocation: Alumno.java, Login.javaSolution: Implement password hashing using BCrypt or similar:
import org.mindrot.jbcrypt.BCrypt;

// Hash password on registration
String hashedPassword = BCrypt.hashpw(contraseña, BCrypt.gensalt());

// Verify password on login
if (BCrypt.checkpw(inputPassword, storedHash)) {
    // Login successful
}
Issue: Data is lost when application closesSolution: Implement data persistence using:
  • File-based storage (JSON, XML)
  • Embedded database (H2, SQLite)
  • Full database (MySQL, PostgreSQL)

Testing Guidelines

Manual Testing Checklist

Before submitting your contribution, test:
1

Welcome Screen

  • Application launches successfully
  • “REGISTRARSE” button navigates to registration
2

Registration

  • All validation messages display correctly
  • Empty field validation works
  • Successful registration shows confirmation
  • Navigation to login works
3

Login

  • Correct credentials allow login
  • Incorrect credentials show error
  • “VOLVER” button returns to registration
4

Course Enrollment

  • Course selection from dropdowns works
  • “Agregar cursos” adds to table
  • “Eliminar fila” removes selected row
  • “Eliminar todo” clears all courses
  • “Matricula” button shows confirmation

Adding Unit Tests

When adding new functionality, include unit tests:
Example Unit Test
package logica;

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class AlumnoTest {
    
    @Test
    void testConstructor() {
        Alumno alumno = new Alumno("Juan", "Pérez", "password123", "12345678");
        
        assertEquals("Juan", alumno.getNombre());
        assertEquals("Pérez", alumno.getApellido());
        assertEquals("12345678", alumno.getDni());
    }
    
    @Test
    void testSettersAndGetters() {
        Alumno alumno = new Alumno();
        alumno.setNombre("María");
        alumno.setApellido("García");
        
        assertEquals("María", alumno.getNombre());
        assertEquals("García", alumno.getApellido());
    }
}
To add testing support, update pom.xml:
pom.xml
<dependencies>
    <!-- Existing dependencies -->
    
    <!-- JUnit 5 for testing -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Pull Request Guidelines

PR Description Template

When creating a pull request, include:
## Description
[Brief description of what this PR does]

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Changes Made
- [List specific changes]
- [Include file names if significant]

## Testing Done
- [ ] Manual testing completed
- [ ] Unit tests added/updated
- [ ] All tests passing

## Screenshots (if applicable)
[Add screenshots showing UI changes]

## Related Issues
Closes #[issue number]

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings introduced

Review Process

1

Automated Checks

Your PR will be automatically checked for:
  • Compilation success
  • Code style violations
  • Test failures
2

Code Review

Maintainers will review your code for:
  • Correctness
  • Code quality
  • Adherence to standards
  • Security concerns
3

Feedback

Address review comments by:
  • Making requested changes
  • Explaining your approach if needed
  • Pushing updates to your branch
4

Merge

Once approved, maintainers will merge your PR.

Reporting Issues

Found a bug? Report it!

Issue Template

## Bug Description
[Clear description of the bug]

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. Enter '...'
4. See error

## Expected Behavior
[What you expected to happen]

## Actual Behavior
[What actually happened]

## Screenshots
[If applicable]

## Environment
- OS: [e.g., Windows 11, macOS 13, Ubuntu 22.04]
- Java Version: [e.g., OpenJDK 20]
- Maven Version: [e.g., 3.9.5]

## Additional Context
[Any other relevant information]

Communication

GitHub Issues

Use for bug reports and feature requests

Pull Requests

Use for code discussions and reviews

Discussions

Use for questions and general discussions

Documentation

Help improve these docs!

Recognition

Contributors will be:
  • Listed in the project’s CONTRIBUTORS.md file
  • Mentioned in release notes
  • Credited in commit history
All contributions, no matter how small, are valued and appreciated!

Resources

Development Setup

Configure your development environment

Building the Project

Learn the build process

Java Documentation

Official Java 20 documentation

Swing Tutorial

Learn Java Swing GUI development

Thank you for contributing to MatriculaUniPoo! Your efforts help make this project better for everyone.

Build docs developers (and LLMs) love