Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
317 lines (213 loc) · 9.6 KB

CONTRIBUTING.md

File metadata and controls

317 lines (213 loc) · 9.6 KB
Raw

Contributing to DedSec Project

English

Για να μεταβείτε στην Ελληνική έκδοση, συνεχίστε Πατώντας Εδώ.

The DedSec Project accepts focused pull requests for bug fixes, documentation, translations, portability improvements, tests, security hardening, and useful features that match the project's educational and lawful-use goals.

Contribution Workflow
  1. Fork the repository.
  2. Create a branch for one focused change.
  3. Make the smallest change needed for the goal.
  4. Keep English and Greek project content synchronized where the changed feature exists in both editions.
  5. Add or update automated tests when behavior changes.
  6. Run the checks described in TESTING.md.
  7. Open a pull request and explain:
    • what changed,
    • why it changed,
    • how it was tested,
    • platform-specific limitations,
    • any security impact.

Pull requests may be declined when they are unsafe, unrelated, incomplete, misleading, intentionally harmful, or incompatible with the direction of the project.

Required Testing Policy

Major new functionality and significant behavior changes must include new or updated automated tests.

This applies to changes involving:

  • project behavior,
  • setup,
  • platform detection,
  • path handling,
  • security-sensitive logic,
  • major user-visible functionality.

If full automated testing is technically impractical because of hardware, Android permissions, external services, an interactive UI, or another environment that cannot safely run in CI:

  • explain why in the pull request,
  • add the safest automated coverage that is practical,
  • document the manual verification performed.

Bug fixes should include a regression test whenever the defect can be reproduced safely and automatically.

A behavior-changing pull request should not be merged with failing tests.

Quality Checks

Run:

python -m pytest

When Ruff is available:

ruff check .

Shell scripts are syntax-checked by the test suite and are also checked with ShellCheck in CI.

See TESTING.md for the complete process.

Test Safety

The baseline test suite must not:

  • launch operational tools,
  • start services unnecessarily,
  • access accounts,
  • collect personal information,
  • scan third-party systems,
  • modify the host system.

Tests should prefer:

  • temporary directories,
  • mocked or local-only inputs,
  • parsing and validation,
  • pure functions,
  • non-operative CLI modes such as --help,
  • static contract checks when direct execution would be unsafe.
Python And Shell Quality Rules

Python source is checked with Ruff.

The repository initially focuses on high-confidence correctness checks so existing scripts can be validated without forcing unrelated style-only rewrites.

New code should not introduce new Ruff findings.

Shell code must pass:

bash -n <script>

and the CI ShellCheck step.

Where a warning is intentionally not applicable, suppress it narrowly and document the reason close to the affected code.

Documentation And Bilingual Maintenance

Update documentation when a change affects:

  • installation,
  • supported platforms,
  • commands,
  • file paths,
  • security behavior,
  • user-visible functionality,
  • requirements,
  • dependencies.

English and Greek documentation must remain synchronized where both editions exist.

Security

Do not publish suspected undisclosed vulnerabilities in a public issue.

Follow SECURITY.md for private vulnerability reporting.

Never commit real:

  • passwords,
  • session cookies,
  • access tokens,
  • API keys,
  • private keys,
  • credential dumps,
  • private personal data.

Ελληνικά

To return to the English version, continue By Clicking Here.

Το DedSec Project δέχεται στοχευμένα pull requests για bug fixes, documentation, μεταφράσεις, portability improvements, tests, security hardening και χρήσιμα features που ταιριάζουν στον εκπαιδευτικό και νόμιμο χαρακτήρα του project.

Διαδικασία Συνεισφοράς
  1. Κάνε fork το repository.
  2. Δημιούργησε branch για μία συγκεκριμένη αλλαγή.
  3. Κάνε τη μικρότερη αλλαγή που απαιτείται.
  4. Κράτησε συγχρονισμένο το English και Greek περιεχόμενο όπου το feature υπάρχει και στις δύο εκδόσεις.
  5. Πρόσθεσε ή ενημέρωσε automated tests όταν αλλάζει behavior.
  6. Τρέξε τους ελέγχους του TESTING.md.
  7. Άνοιξε pull request και εξήγησε:
    • τι άλλαξε,
    • γιατί άλλαξε,
    • πώς δοκιμάστηκε,
    • platform-specific limitations,
    • τυχόν security impact.

Pull requests μπορεί να απορριφθούν όταν είναι unsafe, unrelated, incomplete, misleading, intentionally harmful ή ασύμβατα με την κατεύθυνση του project.

Υποχρεωτική Πολιτική Tests

Κάθε σημαντική νέα λειτουργία και κάθε ουσιαστική αλλαγή συμπεριφοράς πρέπει να συνοδεύεται από νέα ή ενημερωμένα automated tests.

Αυτό περιλαμβάνει αλλαγές σε:

  • project behavior,
  • setup,
  • platform detection,
  • path handling,
  • security-sensitive logic,
  • σημαντικές user-visible λειτουργίες.

Αν το πλήρες automated testing δεν είναι πρακτικό λόγω hardware, Android permissions, external services, interactive UI ή άλλου environment που δεν μπορεί να τρέξει με ασφάλεια σε CI:

  • εξήγησε το γιατί στο pull request,
  • πρόσθεσε την ασφαλέστερη αυτοματοποιημένη κάλυψη που είναι εφικτή,
  • κατέγραψε το manual verification.

Τα bug fixes πρέπει να συνοδεύονται από regression test όταν το bug μπορεί να αναπαραχθεί με ασφάλεια και αυτόματα.

Pull request που αλλάζει behavior δεν πρέπει να γίνεται merge με failing tests.

Έλεγχοι Ποιότητας

Τρέξε:

python -m pytest

Όταν είναι διαθέσιμο το Ruff:

ruff check .

Τα shell scripts περνούν syntax check από το test suite και ShellCheck στο CI.

Δες το TESTING.md για ολόκληρη τη διαδικασία.

Ασφάλεια Tests

Το βασικό test suite δεν πρέπει να:

  • εκκινεί operational tools,
  • ανοίγει άσκοπα services,
  • αποκτά πρόσβαση σε accounts,
  • συλλέγει προσωπικά δεδομένα,
  • κάνει scans τρίτων συστημάτων,
  • αλλάζει το host system.

Τα tests πρέπει να προτιμούν:

  • temporary directories,
  • mocked ή local-only inputs,
  • parsing και validation,
  • pure functions,
  • non-operative CLI modes όπως --help,
  • static contract checks όταν η άμεση εκτέλεση δεν είναι ασφαλής.
Κανόνες Ποιότητας Python Και Shell

Το Python source ελέγχεται με Ruff.

Οι αρχικοί κανόνες εστιάζουν σε high-confidence correctness checks ώστε να ελέγχεται ο υπάρχων κώδικας χωρίς άσχετες μαζικές style-only αλλαγές.

Νέος κώδικας δεν πρέπει να εισάγει νέα Ruff findings.

Το shell code πρέπει να περνά:

bash -n <script>

και το ShellCheck του CI.

Αν κάποιο warning δεν εφαρμόζεται σκόπιμα, πρέπει να γίνεται στενή εξαίρεση και να τεκμηριώνεται κοντά στον σχετικό κώδικα.

Documentation Και Δίγλωσση Συντήρηση

Ενημέρωσε το documentation όταν μια αλλαγή επηρεάζει:

  • installation,
  • supported platforms,
  • commands,
  • file paths,
  • security behavior,
  • user-visible functionality,
  • requirements,
  • dependencies.

Το English και Greek documentation πρέπει να παραμένει συγχρονισμένο όπου υπάρχουν και οι δύο εκδόσεις.

Ασφάλεια

Μην δημοσιεύεις suspected undisclosed vulnerabilities σε public issue.

Ακολούθησε το SECURITY.md για private vulnerability reporting.

Μην κάνεις ποτέ commit πραγματικά:

  • passwords,
  • session cookies,
  • access tokens,
  • API keys,
  • private keys,
  • credential dumps,
  • private personal data.