/Fahri-Hilm/Smart_Absen_Facerecognation-2025-Kelompok4

Wiki directory

Browse AI-generated documentation for any repository.

Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

This guide provides instructions for developers wishing to contribute to the Smart Absen Face Recognition System. It covers everything from setting up the development environment to submitting code changes. Following these guidelines helps maintain code quality and streamlines the review process. For a detailed installation guide, please refer to the Installation Guide.

Sources: CONTRIBUTING.md:3-3, README.md:121-124

Getting Started

To begin contributing, you must first set up the project on your local machine. This involves forking and cloning the repository, setting up a Python environment, and configuring the database.

Sources: CONTRIBUTING.md:15-15

Prerequisites

Ensure the following software is installed on your system before proceeding.

Requirement	Recommended Version	How to Check
Python	3.8+	`python --version`
MySQL Server	8.0+	`mysql --version`
Git	Latest	`git --version`
VS Code	Latest	(Recommended Editor)

Sources: CONTRIBUTING.md:17-22, INSTALLATION.md:20-27

Quick Setup

The following diagram and steps outline the initial setup process for new contributors.

This diagram shows the workflow for setting up the development environment.

Generating architecture diagram...

Sources: CONTRIBUTING.md:24-39

Fork and Clone: Fork the main repository on GitHub, then clone your fork to your local machine.

git clone https://github.com/YOUR_USERNAME/Smart_Absen_Facerecognation-2025-Kelompok4.git
cd Smart_Absen_Facerecognation-2025-Kelompok4

Sources: CONTRIBUTING.md:27-29

Add Upstream Remote: Add the original repository as an upstream remote to keep your fork synced.
```
git remote add upstream https://github.com/Fahri-Hilm/Smart_Absen_Facerecognation-2025-Kelompok4.git
```
Sources: CONTRIBUTING.md:31-32
Setup Environment: Create and activate a Python virtual environment, then install the required packages.
```
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
Sources: CONTRIBUTING.md:34-36
Configure: Set up your database and create a .env file for environment variables. Refer to INSTALLATION.md for detailed database setup.
Sources: CONTRIBUTING.md:38-39
Run: Start the application.
```
python app.py
```
Sources: CONTRIBUTING.md:41-42

Development Setup

Recommended VS Code Extensions

For a consistent development experience, it is recommended to install the following VS Code extensions.

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "mtxr.sqltools",
    "ritwickdey.LiveServer"
  ]
}

Sources: CONTRIBUTING.md:48-56

Environment Variables

Create a .env file in the project root for local configuration. This file should not be committed to version control.

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=absensi_karyawan_db
SECRET_KEY=your-dev-secret-key
DEBUG=True

Sources: CONTRIBUTING.md:58-66, SECURITY.md:7-12

Project Structure

The project follows a modular structure to separate concerns. The diagram below illustrates the main components.

This graph shows the high-level structure of the project directories and key files.

Generating architecture diagram...

Sources: CONTRIBUTING.md:71-91, CLEANUP_REPORT.md:58-75

Key Files

The following table lists key files and their designated owners.

File	Purpose	Owner
`app.py`	Main Flask app, all routes, FR logic, QR sync	Backend
`database.py`	Database connection handler and operations	Backend
`templates/*.html`	UI templates using Jinja2	Frontend
`static/css/*.css`	Styling and theme definitions	Frontend

Sources: CONTRIBUTING.md:93-99

Coding Standards

Adherence to coding standards is mandatory to ensure code quality and readability.

Naming Conventions

Type	Convention	Example
Variables	`snake_case`	`employee_name`
Functions	`snake_case`	`get_employee()`
Classes	`PascalCase`	`EmployeeManager`
Constants	`UPPER_SNAKE`	`MAX_RETRY_COUNT`
Files	`snake_case`	`employee_manager.py`

Sources: CONTRIBUTING.md:111-118

Python Style Guide

Follow PEP 8. Functions should have clear names, type hints, and docstrings.

# ✅ Good
def get_employee_by_id(employee_id: int) -> dict:
    """
    Mengambil data karyawan berdasarkan ID.
    
    Args:
        employee_id: ID karyawan
        
    Returns:
        Dictionary berisi data karyawan
    """
    pass

# ❌ Bad
def getEmp(id):
    pass

Sources: CONTRIBUTING.md:103-109

HTML/CSS Standards

Use semantic HTML and avoid "div soup".

<!-- ✅ Good: Semantic HTML -->
<section class="attendance-form">
    <header class="form-header">
        <h2>Absensi Karyawan</h2>
    </header>
</section>

<!-- ❌ Bad: Div soup -->
<div class="div1">
    <div class="div2">
        <div class="div3">
        </div>
    </div>
</div>

Sources: CONTRIBUTING.md:120-135

JavaScript Standards

Use modern ES6+ syntax with descriptive function and variable names.

// ✅ Good: ES6+, descriptive names
const fetchEmployeeData = async (employeeId) => {
    try {
        const response = await fetch(`/api/employee/${employeeId}`);
        return await response.json();
    } catch (error) {
        console.error('Failed to fetch employee:', error);
        throw error;
    }
};

Sources: CONTRIBUTING.md:137-148

Git Workflow

The project uses a feature-branch Git workflow. All changes must be made in a dedicated branch and merged into main via a Pull Request.

Branch Naming Convention

Branches must be named according to the type of change being made.

Format: <type>/<description>

Types:

feature/: For a new feature.
bugfix/: For a non-urgent bug fix.
hotfix/: For an urgent production fix.
docs/: For documentation changes.
refactor/: For code refactoring without changing functionality.

Examples:

feature/dashboard-training
bugfix/camera-not-detected

Sources: CONTRIBUTING.md:152-167

Commit Messages

Commit messages must follow the Conventional Commits specification.

Format: <type>: <description>

Type	Description
`feat`	A new feature
`fix`	A bug fix
`docs`	Documentation only changes
`style`	Changes that do not affect the meaning of the code (white-space, formatting)
`refactor`	A code change that neither fixes a bug nor adds a feature
`test`	Adding missing tests or correcting existing tests
`chore`	Changes to the build process or auxiliary tools

Examples:

feat: add face training dashboard
fix: camera not detected on firefox

Sources: CONTRIBUTING.md:169-184, CHANGELOG.md:10-10

Workflow Steps

This diagram shows the standard Git workflow for contributors.

Generating architecture diagram...

Sources: CONTRIBUTING.md:186-199

Pull Request Process

All code is merged into the main branch through Pull Requests (PRs).

Before Creating a PR

Ensure your contribution meets the following criteria:

Code runs without errors.
No merge conflicts with the main branch.
Manual testing has been completed.
Code adheres to the style guide.
Documentation is updated if necessary.

Sources: CONTRIBUTING.md:203-209

PR Template

Use the following template when creating a Pull Request.

## Description
Jelaskan perubahan yang dilakukan.

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

## Testing
Langkah-langkah untuk test:
1. ...
2. ...

## Screenshots (if applicable)
Tambahkan screenshot jika ada perubahan UI.

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No new warnings

Sources: CONTRIBUTING.md:211-231

Review Process

The PR review process involves automated checks, peer review, and final testing before being merged.

This sequence diagram illustrates the steps from PR creation to merging.

Generating architecture diagram...

Sources: CONTRIBUTING.md:233-238

Testing

All contributions must be tested manually before creating a Pull Request.

Manual Testing Checklist

Feature	Test Case	Status
Core	QR code generation works	[ ]
	QR scan redirects correctly	[ ]
	Face detection works	[ ]
	Face recognition identifies correctly	[ ]
	Attendance data saved to database	[ ]
Admin	Admin login works	[ ]
	Admin can view employees	[ ]
	Admin can view attendance	[ ]
Cross-browser	Chrome, Firefox, Edge	[ ]
Responsive	Desktop, Laptop, Mobile	[ ]

Sources: CONTRIBUTING.md:242-261

Automated Testing

Automated tests are planned for future implementation.

# (Future implementation)
python -m pytest tests/

Sources: CONTRIBUTING.md:263-266

Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

Sources: CONTRIBUTING.md:3-3, README.md:121-124

Getting Started

To begin contributing, you must first set up the project on your local machine. This involves forking and cloning the repository, setting up a Python environment, and configuring the database.

Sources: CONTRIBUTING.md:15-15

Prerequisites

Ensure the following software is installed on your system before proceeding.

Requirement	Recommended Version	How to Check
Python	3.8+	`python --version`
MySQL Server	8.0+	`mysql --version`
Git	Latest	`git --version`
VS Code	Latest	(Recommended Editor)

Sources: CONTRIBUTING.md:17-22, INSTALLATION.md:20-27

Quick Setup

The following diagram and steps outline the initial setup process for new contributors.

This diagram shows the workflow for setting up the development environment.

Generating architecture diagram...

Sources: CONTRIBUTING.md:24-39

Fork and Clone: Fork the main repository on GitHub, then clone your fork to your local machine.

git clone https://github.com/YOUR_USERNAME/Smart_Absen_Facerecognation-2025-Kelompok4.git
cd Smart_Absen_Facerecognation-2025-Kelompok4

Sources: CONTRIBUTING.md:27-29

Add Upstream Remote: Add the original repository as an upstream remote to keep your fork synced.
```
git remote add upstream https://github.com/Fahri-Hilm/Smart_Absen_Facerecognation-2025-Kelompok4.git
```
Sources: CONTRIBUTING.md:31-32
Setup Environment: Create and activate a Python virtual environment, then install the required packages.
```
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
Sources: CONTRIBUTING.md:34-36
Configure: Set up your database and create a .env file for environment variables. Refer to INSTALLATION.md for detailed database setup.
Sources: CONTRIBUTING.md:38-39
Run: Start the application.
```
python app.py
```
Sources: CONTRIBUTING.md:41-42

Development Setup

Recommended VS Code Extensions

For a consistent development experience, it is recommended to install the following VS Code extensions.

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "mtxr.sqltools",
    "ritwickdey.LiveServer"
  ]
}

Sources: CONTRIBUTING.md:48-56

Environment Variables

Create a .env file in the project root for local configuration. This file should not be committed to version control.

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=absensi_karyawan_db
SECRET_KEY=your-dev-secret-key
DEBUG=True

Sources: CONTRIBUTING.md:58-66, SECURITY.md:7-12

Project Structure

The project follows a modular structure to separate concerns. The diagram below illustrates the main components.

This graph shows the high-level structure of the project directories and key files.

Generating architecture diagram...

Sources: CONTRIBUTING.md:71-91, CLEANUP_REPORT.md:58-75

Key Files

The following table lists key files and their designated owners.

File	Purpose	Owner
`app.py`	Main Flask app, all routes, FR logic, QR sync	Backend
`database.py`	Database connection handler and operations	Backend
`templates/*.html`	UI templates using Jinja2	Frontend
`static/css/*.css`	Styling and theme definitions	Frontend

Sources: CONTRIBUTING.md:93-99

Coding Standards

Adherence to coding standards is mandatory to ensure code quality and readability.

Naming Conventions

Type	Convention	Example
Variables	`snake_case`	`employee_name`
Functions	`snake_case`	`get_employee()`
Classes	`PascalCase`	`EmployeeManager`
Constants	`UPPER_SNAKE`	`MAX_RETRY_COUNT`
Files	`snake_case`	`employee_manager.py`

Sources: CONTRIBUTING.md:111-118

Python Style Guide

Follow PEP 8. Functions should have clear names, type hints, and docstrings.

# ✅ Good
def get_employee_by_id(employee_id: int) -> dict:
    """
    Mengambil data karyawan berdasarkan ID.
    
    Args:
        employee_id: ID karyawan
        
    Returns:
        Dictionary berisi data karyawan
    """
    pass

# ❌ Bad
def getEmp(id):
    pass

Sources: CONTRIBUTING.md:103-109

HTML/CSS Standards

Use semantic HTML and avoid "div soup".

<!-- ✅ Good: Semantic HTML -->
<section class="attendance-form">
    <header class="form-header">
        <h2>Absensi Karyawan</h2>
    </header>
</section>

<!-- ❌ Bad: Div soup -->
<div class="div1">
    <div class="div2">
        <div class="div3">
        </div>
    </div>
</div>

Sources: CONTRIBUTING.md:120-135

JavaScript Standards

Use modern ES6+ syntax with descriptive function and variable names.

// ✅ Good: ES6+, descriptive names
const fetchEmployeeData = async (employeeId) => {
    try {
        const response = await fetch(`/api/employee/${employeeId}`);
        return await response.json();
    } catch (error) {
        console.error('Failed to fetch employee:', error);
        throw error;
    }
};

Sources: CONTRIBUTING.md:137-148

Git Workflow

The project uses a feature-branch Git workflow. All changes must be made in a dedicated branch and merged into main via a Pull Request.

Branch Naming Convention

Branches must be named according to the type of change being made.

Format: <type>/<description>

Types:

feature/: For a new feature.
bugfix/: For a non-urgent bug fix.
hotfix/: For an urgent production fix.
docs/: For documentation changes.
refactor/: For code refactoring without changing functionality.

Examples:

feature/dashboard-training
bugfix/camera-not-detected

Sources: CONTRIBUTING.md:152-167

Commit Messages

Commit messages must follow the Conventional Commits specification.

Format: <type>: <description>

Type	Description
`feat`	A new feature
`fix`	A bug fix
`docs`	Documentation only changes
`style`	Changes that do not affect the meaning of the code (white-space, formatting)
`refactor`	A code change that neither fixes a bug nor adds a feature
`test`	Adding missing tests or correcting existing tests
`chore`	Changes to the build process or auxiliary tools

Examples:

feat: add face training dashboard
fix: camera not detected on firefox

Sources: CONTRIBUTING.md:169-184, CHANGELOG.md:10-10

Workflow Steps

This diagram shows the standard Git workflow for contributors.

Generating architecture diagram...

Sources: CONTRIBUTING.md:186-199

Pull Request Process

All code is merged into the main branch through Pull Requests (PRs).

Before Creating a PR

Ensure your contribution meets the following criteria:

Code runs without errors.
No merge conflicts with the main branch.
Manual testing has been completed.
Code adheres to the style guide.
Documentation is updated if necessary.

Sources: CONTRIBUTING.md:203-209

PR Template

Use the following template when creating a Pull Request.

## Description
Jelaskan perubahan yang dilakukan.

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

## Testing
Langkah-langkah untuk test:
1. ...
2. ...

## Screenshots (if applicable)
Tambahkan screenshot jika ada perubahan UI.

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No new warnings

Sources: CONTRIBUTING.md:211-231

Review Process

The PR review process involves automated checks, peer review, and final testing before being merged.

This sequence diagram illustrates the steps from PR creation to merging.

Generating architecture diagram...

Sources: CONTRIBUTING.md:233-238

Testing

All contributions must be tested manually before creating a Pull Request.

Manual Testing Checklist

Feature	Test Case	Status
Core	QR code generation works	[ ]
	QR scan redirects correctly	[ ]
	Face detection works	[ ]
	Face recognition identifies correctly	[ ]
	Attendance data saved to database	[ ]
Admin	Admin login works	[ ]
	Admin can view employees	[ ]
	Admin can view attendance	[ ]
Cross-browser	Chrome, Firefox, Edge	[ ]
Responsive	Desktop, Laptop, Mobile	[ ]

Sources: CONTRIBUTING.md:242-261

Automated Testing

Automated tests are planned for future implementation.

# (Future implementation)
python -m pytest tests/

Sources: CONTRIBUTING.md:263-266