Skip to content

Commit a8cc7b7

Browse files
Copilotjaypatrick
Copilot
and
jaypatrick
authored
Restructure repository to follow GitHub and monorepo standards (#193)
* Initial plan * Consolidate API specs and organize tools/docs directories Co-authored-by: jaypatrick <1800595+jaypatrick@users.noreply.github.com> * Consolidate scripting projects into src/shell and src/powershell Co-authored-by: jaypatrick <1800595+jaypatrick@users.noreply.github.com> * Add comprehensive documentation for restructured repository Co-authored-by: jaypatrick <1800595+jaypatrick@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jaypatrick <1800595+jaypatrick@users.noreply.github.com>
1 parent 7d423aa commit a8cc7b7

48 files changed

Lines changed: 10631 additions & 40 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/build-scripts-tests.yml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,16 @@ on:
66
paths:
77
- 'build.sh'
88
- 'build.ps1'
9-
- 'test-build-scripts.sh'
10-
- 'test-build-scripts.ps1'
9+
- 'tools/test-build-scripts.sh'
10+
- 'tools/test-build-scripts.ps1'
1111
- '.github/workflows/build-scripts-tests.yml'
1212
pull_request:
1313
branches: [ "main" ]
1414
paths:
1515
- 'build.sh'
1616
- 'build.ps1'
17-
- 'test-build-scripts.sh'
18-
- 'test-build-scripts.ps1'
17+
- 'tools/test-build-scripts.sh'
18+
- 'tools/test-build-scripts.ps1'
1919
- '.github/workflows/build-scripts-tests.yml'
2020
workflow_dispatch:
2121

@@ -38,10 +38,10 @@ jobs:
3838
toolchain: stable
3939

4040
- name: Make test script executable
41-
run: chmod +x test-build-scripts.sh
41+
run: chmod +x tools/test-build-scripts.sh
4242

4343
- name: Run Bash build script tests
44-
run: ./test-build-scripts.sh
44+
run: ./tools/test-build-scripts.sh
4545

4646
- name: Upload test results
4747
if: always()
@@ -70,7 +70,7 @@ jobs:
7070
toolchain: stable
7171

7272
- name: Run PowerShell build script tests
73-
run: pwsh -File test-build-scripts.ps1
73+
run: pwsh -File tools/test-build-scripts.ps1
7474

7575
test-windows:
7676
name: Test Build Script (Windows)
@@ -90,7 +90,7 @@ jobs:
9090
toolchain: stable
9191

9292
- name: Run PowerShell build script tests
93-
run: .\test-build-scripts.ps1
93+
run: .\tools\test-build-scripts.ps1
9494
shell: pwsh
9595

9696
- name: Test actual build (Rust + .NET)

‎.github/workflows/validation-compliance.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,8 @@ jobs:
7272

7373
- name: Run compliance check
7474
run: |
75-
chmod +x scripts/check-validation-compliance.sh
76-
./scripts/check-validation-compliance.sh
75+
chmod +x tools/check-validation-compliance.sh
76+
./tools/check-validation-compliance.sh
7777
7878
- name: Generate compliance report
7979
if: always()
@@ -85,7 +85,7 @@ jobs:
8585
echo "" >> compliance-report.md
8686
echo "## Status" >> compliance-report.md
8787
echo "" >> compliance-report.md
88-
./scripts/check-validation-compliance.sh >> compliance-report.md 2>&1 || true
88+
./tools/check-validation-compliance.sh >> compliance-report.md 2>&1 || true
8989
9090
- name: Upload compliance report
9191
if: always()

‎CONTRIBUTING.md‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
# Contributing to Ad-Blocking Repository
2+
3+
Thank you for your interest in contributing to the ad-blocking repository! This document provides guidelines for contributing to this multi-language monorepo.
4+
5+
## Table of Contents
6+
7+
- [Code of Conduct](#code-of-conduct)
8+
- [Getting Started](#getting-started)
9+
- [Repository Structure](#repository-structure)
10+
- [Development Workflow](#development-workflow)
11+
- [Coding Standards](#coding-standards)
12+
- [Testing Requirements](#testing-requirements)
13+
- [Pull Request Process](#pull-request-process)
14+
- [Security](#security)
15+
16+
## Code of Conduct
17+
18+
By participating in this project, you agree to maintain a respectful, inclusive, and harassment-free environment for everyone.
19+
20+
## Getting Started
21+
22+
### Prerequisites
23+
24+
Install the required tools for the language you're working with:
25+
26+
- **TypeScript/Deno**: [Deno 2.0+](https://deno.land/)
27+
- **.NET**: [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
28+
- **Python**: [Python 3.9+](https://www.python.org/)
29+
- **Rust**: [Rust 1.83+](https://rustup.rs/)
30+
- **PowerShell**: [PowerShell 7+](https://github.com/PowerShell/PowerShell)
31+
32+
### Initial Setup
33+
34+
```bash
35+
# Clone the repository
36+
git clone https://github.com/jaypatrick/ad-blocking.git
37+
cd ad-blocking
38+
39+
# Build all projects (or specific language ecosystems)
40+
./build.sh # All projects
41+
./build.sh --rust # Rust only
42+
./build.sh --dotnet # .NET only
43+
```
44+
45+
See [README.md](README.md) for detailed setup instructions.
46+
47+
## Repository Structure
48+
49+
This is a multi-language monorepo organized as follows:
50+
51+
```
52+
ad-blocking/
53+
├── api/ # Centralized OpenAPI specifications
54+
├── docs/ # All documentation
55+
├── tools/ # Build and utility scripts
56+
├── data/ # Filter rules and compilation data
57+
├── src/ # Source code organized by language
58+
│ ├── adguard-api-dotnet/ # C# API SDK
59+
│ ├── adguard-api-rust/ # Rust API SDK
60+
│ ├── adguard-api-typescript/ # TypeScript API SDK
61+
│ ├── adguard-api-powershell/ # PowerShell API client
62+
│ ├── rules-compiler-dotnet/ # .NET rules compiler
63+
│ ├── rules-compiler-rust/ # Rust rules compiler
64+
│ ├── rules-compiler-typescript/ # TypeScript rules compiler
65+
│ ├── rules-compiler-python/ # Python rules compiler
66+
│ ├── powershell-modules/ # PowerShell modules
67+
│ ├── shell-scripts/ # Shell script utilities
68+
│ ├── adguard-validation/ # Rust validation library
69+
│ └── linear/ # Linear integration
70+
└── .github/ # GitHub workflows and configuration
71+
```
72+
73+
### Important Locations
74+
75+
- **OpenAPI specs**: `api/` (single source of truth, don't duplicate)
76+
- **Documentation**: `docs/` (project-wide docs, guides, references)
77+
- **Build scripts**: Root level (`build.sh`, `build.ps1`) and `tools/`
78+
- **Tests**: Within each project's directory
79+
80+
## Development Workflow
81+
82+
### 1. Create a Branch
83+
84+
```bash
85+
git checkout -b feature/your-feature-name
86+
# or
87+
git checkout -b fix/issue-description
88+
```
89+
90+
### 2. Make Changes
91+
92+
Follow the coding standards for your language (see below).
93+
94+
### 3. Test Your Changes
95+
96+
```bash
97+
# Test specific language ecosystem
98+
./build.sh --rust && cargo test --workspace
99+
./build.sh --dotnet && dotnet test
100+
101+
# Or use language-specific commands
102+
cd src/rules-compiler-typescript && deno task test
103+
cd src/rules-compiler-python && pytest
104+
```
105+
106+
### 4. Lint Your Code
107+
108+
```bash
109+
# TypeScript/Deno
110+
deno lint
111+
112+
# .NET
113+
dotnet format
114+
115+
# Python
116+
ruff check rules_compiler/
117+
118+
# Rust
119+
cargo clippy --workspace
120+
121+
# PowerShell
122+
Invoke-ScriptAnalyzer -Path src/powershell-modules -Recurse
123+
```
124+
125+
### 5. Commit Changes
126+
127+
Use clear, descriptive commit messages:
128+
129+
```bash
130+
git add .
131+
git commit -m "Add feature: description of what you added"
132+
# or
133+
git commit -m "Fix: description of what was fixed"
134+
```
135+
136+
## Coding Standards
137+
138+
### General Principles
139+
140+
- Write clear, self-documenting code
141+
- Follow existing patterns in each language/component
142+
- Add comments only when code intent is not obvious
143+
- Maintain consistency with the existing codebase
144+
145+
### Language-Specific Standards
146+
147+
#### C# (.NET)
148+
- Use C# 14 features with .NET 10
149+
- Enable nullable reference types (`#nullable enable`)
150+
- Use dependency injection for services
151+
- Use async/await for all I/O operations
152+
- Follow [Microsoft C# Coding Conventions](https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)
153+
154+
#### TypeScript/Deno
155+
- Target ES2022, Node.js 18+
156+
- Enable strict mode in tsconfig.json
157+
- Use `node:` prefixed imports for built-ins (`node:fs`, `node:path`)
158+
- Use SHA-384 for hashing (never SHA-256)
159+
- Add JSDoc for exported functions
160+
161+
#### Python
162+
- Python 3.9+ compatibility
163+
- Follow PEP 8 style guide
164+
- Use type hints (typing module)
165+
- Line length: 100 characters
166+
- Use pytest for testing
167+
- Use mypy for type checking
168+
169+
#### Rust
170+
- Edition 2021
171+
- Follow standard Rust conventions
172+
- Use cargo fmt for formatting
173+
- Use clippy for linting
174+
- Document public APIs
175+
176+
#### PowerShell
177+
- PowerShell 7+ (Core, not Windows PowerShell 5.1)
178+
- Use approved verbs (Get-, Set-, New-, Invoke-, etc.)
179+
- Module structure: `.psm1` + `.psd1` manifest
180+
- Never use `ConvertTo-SecureString` with plaintext secrets
181+
- Use Pester v5 for tests
182+
183+
### Security Practices
184+
185+
**NEVER commit:**
186+
- API keys, tokens, passwords
187+
- `.env` files (only `.env.example` templates)
188+
189+
**Always:**
190+
- Use environment variables for secrets
191+
- Validate input from external sources
192+
- Use HTTPS for remote sources
193+
- Verify hashes for downloaded files
194+
195+
## Testing Requirements
196+
197+
### Required Tests
198+
199+
All new features and bug fixes must include appropriate tests:
200+
201+
- **Unit tests**: Test individual functions/methods
202+
- **Integration tests**: Test component interactions
203+
- **End-to-end tests**: Test complete workflows (where applicable)
204+
205+
### Test Coverage
206+
207+
- Maintain existing test coverage levels
208+
- Aim for >80% coverage for new code
209+
- All public APIs must have tests
210+
211+
### Running Tests
212+
213+
```bash
214+
# Run all tests
215+
./tools/test-build-scripts.sh # Build script tests
216+
217+
# Language-specific tests
218+
cd src/rules-compiler-typescript && deno task test
219+
cd src/rules-compiler-dotnet && dotnet test
220+
cd src/rules-compiler-python && pytest
221+
cd src/rules-compiler-rust && cargo test
222+
cd src/powershell-modules && Invoke-Pester
223+
```
224+
225+
## Pull Request Process
226+
227+
### Before Submitting
228+
229+
1. ✅ All tests pass locally
230+
2. ✅ Code is linted and formatted
231+
3. ✅ Documentation is updated (if needed)
232+
4. ✅ Commit messages are clear
233+
5. ✅ No sensitive data in commits
234+
235+
### PR Description
236+
237+
Include in your PR description:
238+
239+
- **Summary**: What does this PR do?
240+
- **Motivation**: Why is this change needed?
241+
- **Testing**: How was this tested?
242+
- **Breaking Changes**: Any breaking changes?
243+
- **Related Issues**: Link to related issues
244+
245+
### Review Process
246+
247+
1. Automated checks must pass (CI/CD workflows)
248+
2. At least one maintainer review required
249+
3. Address all review comments
250+
4. Squash commits if requested
251+
5. Maintainer will merge when approved
252+
253+
### CI/CD Checks
254+
255+
All PRs must pass:
256+
257+
- ✅ Build scripts tests
258+
- ✅ Language-specific linting
259+
- ✅ Unit and integration tests
260+
- ✅ Security scans (CodeQL, DevSkim)
261+
- ✅ Dependency checks
262+
263+
## Security
264+
265+
### Reporting Vulnerabilities
266+
267+
**DO NOT** open public issues for security vulnerabilities.
268+
269+
Instead, follow the process in [SECURITY.md](SECURITY.md).
270+
271+
### Security Requirements
272+
273+
- All filter compilation includes mandatory validation
274+
- Use centralized validation library for security checks
275+
- HTTPS enforcement for remote sources
276+
- SHA-384 hash verification for integrity
277+
- No plaintext secrets in code
278+
279+
## Questions?
280+
281+
- Check existing [documentation](docs/)
282+
- Review [README.md](README.md)
283+
- Look at similar existing code
284+
- Ask questions in PR comments
285+
286+
## License
287+
288+
By contributing, you agree that your contributions will be licensed under the same license as the project (GPL-3.0).
289+
290+
---
291+
292+
Thank you for contributing! 🎉

0 commit comments

Comments
 (0)