Skip to content

Commit ed587ec

Browse files
utkarshkgithubutkarshkgithub
committed
feat: restructure project into modular architecture
1 parent a63ccea commit ed587ec

29 files changed

+3498
-31
lines changed

‎.github/Contributor_Guide/Contributing.md‎

Lines changed: 244 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,266 @@
1-
# Contribute to <Project_Name>
1+
# Contributing to Simple Firewall
22

3-
Thank you for taking the time to contribute to <project_name>! We really appreciate it.
3+
Thank you for taking the time to contribute to Simple Firewall! We really appreciate it. This project aims to create an educational DDoS/DoS protection firewall with a user-friendly GUI interface.
44

55
Before contributing, please make sure to read the [Code of Conduct](../../CODE_OF_CONDUCT.md). We expect you to follow it in all your interactions with the project.
66

7-
## New to <Project_Name>?
7+
## New to Simple Firewall?
88

9-
If you are new to <Project_Name>, please take a look at the [documentation](./Project_Tour.md). It is a great place to start.
9+
If you are new to Simple Firewall, please take a look at the [Project Tour](./Project_Tour.md) documentation. It's a great place to start understanding the codebase structure and architecture.
1010

1111
## New Contributor Guide
1212

13-
To get an overview of the codebase, check out the '[README.md](../src/README.md)' file in the `src` directory.
13+
To get an overview of the project:
14+
1. Read the main [README.md](../../README.md) for project overview
15+
2. Check out the [Project Tour](./Project_Tour.md) for detailed code walkthrough
16+
3. Review the [firewall_config.json](../../firewall_config.json) to understand configuration options
17+
4. Explore the new modular structure in [src/](../../src/) directory:
18+
- `src/firewall/core.py` - Main firewall orchestration
19+
- `src/config/loader.py` - Configuration management
20+
- `src/network/packet_handler.py` - Network packet processing
21+
- `main.py` - Modern CLI entry point
1422

15-
that will help you understand the structure of the project.
23+
## Development Environment Setup
24+
25+
### Prerequisites
26+
27+
#### All Platforms
28+
- **Python 3.8+** (recommended 3.10+)
29+
- **Node.js 16+** (for commit hooks and future GUI development)
30+
- **Git** for version control
31+
32+
#### Linux (Primary Development Platform)
33+
```bash
34+
# Ubuntu/Debian
35+
sudo apt update
36+
sudo apt install python3 python3-pip python3-venv nodejs npm
37+
38+
# Arch Linux
39+
sudo pacman -S python python-pip nodejs npm
40+
41+
# CentOS/RHEL
42+
sudo yum install python3 python3-pip nodejs npm
43+
```
44+
45+
#### macOS
46+
```bash
47+
# Using Homebrew
48+
brew install python3 node
49+
50+
# Install Xcode Command Line Tools (required for some Python packages)
51+
xcode-select --install
52+
```
53+
54+
#### Windows
55+
```powershell
56+
# Using Chocolatey (recommended)
57+
choco install python nodejs
58+
59+
# Or download from official websites:
60+
# Python: https://python.org/downloads
61+
# Node.js: https://nodejs.org/downloads
62+
```
63+
64+
### Project Setup
65+
66+
1. **Fork and Clone**
67+
```bash
68+
git clone https://github.com/YOUR_USERNAME/simple_firewall.git
69+
cd simple_firewall
70+
```
71+
72+
2. **Set up Python Environment**
73+
```bash
74+
# Create virtual environment
75+
python3 -m venv venv
76+
77+
# Activate virtual environment
78+
# Linux/macOS:
79+
source venv/bin/activate
80+
# Windows:
81+
venv\Scripts\activate
82+
83+
# Install dependencies
84+
pip install -r requirements.txt
85+
```
86+
87+
3. **Install Development Tools**
88+
```bash
89+
# Install Node.js dependencies (for commit hooks)
90+
npm install
91+
92+
# This will set up Husky git hooks automatically
93+
```
94+
95+
4. **Create Configuration File**
96+
```bash
97+
# Generate configuration template with the new CLI
98+
python3 main.py --create-config
99+
100+
# Edit configuration as needed
101+
nano firewall_config.json
102+
```
103+
104+
### Platform-Specific Notes
105+
106+
#### Linux
107+
- Requires `sudo` privileges for iptables operations
108+
- Install libpcap development headers:
109+
```bash
110+
# Ubuntu/Debian
111+
sudo apt install libpcap-dev
112+
# Arch Linux
113+
sudo pacman -S libpcap
114+
```
115+
116+
#### macOS
117+
- Uses `pfctl` instead of `iptables` (implementation needed)
118+
- Install libpcap via Homebrew:
119+
```bash
120+
brew install libpcap
121+
```
122+
- May require running with `sudo` for packet capture
123+
124+
#### Windows
125+
- Requires Npcap or WinPcap for packet capture
126+
- Uses Windows Firewall API instead of iptables (implementation needed)
127+
- Install Npcap: https://npcap.org/
16128

17129
## How to Contribute
18130

19131
### Reporting Bugs
20132

21-
If you find a bug in the source code, you can help us by [submitting an issue](../ISSUE_TEMPLATE/bug_report.yaml).
133+
Found a bug? Please help us by [creating an issue](https://github.com/OPCODE-Open-Spring-Fest/simple_firewall/issues/new) with:
134+
135+
- **Clear description** of the problem
136+
- **Steps to reproduce** the issue
137+
- **Expected vs actual behavior**
138+
- **Environment details** (OS, Python version, etc.)
139+
- **Log files** if applicable (`firewall.log`)
140+
- **Configuration file** (remove sensitive data)
141+
142+
### Suggesting Features
143+
144+
Have an idea for improvement? We'd love to hear it! Please [create a feature request](https://github.com/OPCODE-Open-Spring-Fest/simple_firewall/issues/new) with:
145+
146+
- **Clear description** of the feature
147+
- **Use case** - why would this be useful?
148+
- **Proposed implementation** (if you have ideas)
149+
- **Alternative solutions** you've considered
150+
151+
### Pull Request Process
152+
153+
1. **Create a Branch**
154+
```bash
155+
git checkout -b feature/your-feature-name
156+
# or
157+
git checkout -b fix/issue-description
158+
```
159+
160+
2. **Follow Coding Standards**
161+
- Use **type hints** for all functions
162+
- Follow **PEP 8** style guide
163+
- Add **docstrings** to classes and functions
164+
- Write **unit tests** for new features
165+
- Update **documentation** as needed
166+
167+
3. **Commit Your Changes**
168+
```bash
169+
# Our commit hooks will validate your message format
170+
git commit -m "feat: add GUI dashboard component"
171+
git commit -m "fix: resolve packet capture on macOS"
172+
git commit -m "docs: update installation instructions"
173+
```
174+
175+
4. **Test Your Changes**
176+
```bash
177+
# Run comprehensive test suite
178+
make test # or python -m pytest tests/ -v
179+
180+
# Test the firewall with new CLI
181+
sudo python3 main.py
182+
183+
# Test configuration management
184+
python3 main.py --create-config
185+
python3 main.py --stats
186+
187+
# Test attack simulation
188+
python3 tools/attack_simulator.py
189+
```
190+
191+
5. **Create Pull Request**
192+
- Use the provided PR template
193+
- Reference related issues with `Fixes #123`
194+
- Include screenshots for GUI changes
195+
- Ensure all checks pass
196+
197+
## Development Guidelines
198+
199+
### Code Style
200+
201+
- **Language**: Python 3.8+ with type hints
202+
- **Formatting**: Black formatter (line length: 88)
203+
- **Linting**: Flake8 with standard configuration
204+
- **Import sorting**: isort
205+
206+
### Commit Convention
207+
208+
We follow [Conventional Commits](https://conventionalcommits.org/):
209+
210+
- `feat:` New features
211+
- `fix:` Bug fixes
212+
- `docs:` Documentation changes
213+
- `style:` Code formatting (no logic changes)
214+
- `refactor:` Code restructuring
215+
- `test:` Adding or updating tests
216+
- `chore:` Maintenance tasks
217+
218+
### Testing
219+
220+
- Write unit tests for new functions
221+
- Use `pytest` framework
222+
- Aim for >80% code coverage
223+
- Include integration tests for major features
224+
225+
### Documentation
226+
227+
- Update docstrings for new/modified functions
228+
- Add type hints to all function signatures
229+
- Update README.md for new features
230+
- Include code examples in documentation
231+
232+
## Current Development Priorities
233+
234+
### Phase 1: Core Stability (Current)
235+
- [ ] Cross-platform compatibility (macOS, Windows)
236+
- [ ] Improved error handling and logging
237+
- [ ] Unit test coverage
238+
- [ ] Performance optimizations
22239

23-
### Suggesting Enhancements
240+
### Phase 2: GUI Development (Upcoming)
241+
- [ ] Web-based dashboard (Flask/FastAPI + React)
242+
- [ ] Real-time statistics visualization
243+
- [ ] Configuration management interface
244+
- [ ] Alert and notification system
24245

25-
If you want to suggest an enhancement to <Project_Name>, please [submit an issue](../ISSUE_TEMPLATE/feature_request.yaml).
246+
### Phase 3: Advanced Features (Future)
247+
- [ ] Machine learning-based attack detection
248+
- [ ] Geographic IP analysis
249+
- [ ] Custom rule engine
250+
- [ ] API for external integrations
26251

27-
### Pull Requests
252+
## Getting Help
28253

29-
If you want to contribute to <Project_Name>, submit a pull request.
254+
- **Questions?** Open a [discussion](https://github.com/OPCODE-Open-Spring-Fest/simple_firewall/discussions)
255+
- **Chat**: Join our community discussions
256+
- **Email**: Contact maintainers for security issues
30257

31-
- url: `https://github.com/OPCODE-Open-Spring-Fest/<project_Name>/compare/branch...YOURGITHUBUSERNAME:<project_Name>:BRANCH?quick_pull=1&template=pr.md`
32-
33-
### Requirements
258+
## Recognition
34259

260+
Contributors will be:
261+
- Listed in our [README.md](../../README.md) contributors section
262+
- Mentioned in release notes for significant contributions
263+
- Invited to join the core team for consistent contributors
35264

36-
### Setup
265+
Thank you for contributing to Simple Firewall! 🛡️
37266

0 commit comments

Comments
 (0)