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
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
Set Up Development Environment
Follow the Development Setup guide to configure your environment with Java 20 and Maven.
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
Make Your Changes
Implement your changes following the coding standards outlined below.
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.
Commit Your Changes
Write clear, descriptive commit messages: git add .
git commit -m "Add course search functionality"
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 : PascalCasepublic class Alumno { }
public class CourseEnrollment { }
Methods and Variables : camelCaseprivate String nombreCompleto ;
public void setNombre ( String nombre) { }
Constants : UPPER_SNAKE_CASEprivate static final int MAX_COURSES = 5 ;
private static final String DEFAULT_LANGUAGE = "es" ;
Packages : lowercasepackage logica;
package igu;
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:
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:
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
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);
}
Always validate user input before processing:
Text Validation
DNI Validation
Password Validation
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:
Welcome Screen
Application launches successfully
“REGISTRARSE” button navigates to registration
Registration
All validation messages display correctly
Empty field validation works
Successful registration shows confirmation
Navigation to login works
Login
Correct credentials allow login
Incorrect credentials show error
“VOLVER” button returns to registration
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:
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:
< 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
Automated Checks
Your PR will be automatically checked for:
Compilation success
Code style violations
Test failures
Code Review
Maintainers will review your code for:
Correctness
Code quality
Adherence to standards
Security concerns
Feedback
Address review comments by:
Making requested changes
Explaining your approach if needed
Pushing updates to your branch
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.