Chummy
94 lines
6.5 KiB
Markdown
94 lines
6.5 KiB
Markdown
# Συνεισφορά στο ZeroClaw
|
|
|
|
Σας ευχαριστούμε για το ενδιαφέρον σας να συνεισφέρετε στο ZeroClaw! Αυτός ο οδηγός θα σας βοηθήσει να ξεκινήσετε.
|
|
|
|
## Συνεισφέροντες για πρώτη φορά
|
|
|
|
Καλώς ήρθατε — οι συνεισφορές κάθε μεγέθους είναι πολύτιμες. Εάν αυτή είναι η πρώτη σας συνεισφορά, δείτε πώς μπορείτε να ξεκινήσετε:
|
|
|
|
1. **Βρείτε ένα ζήτημα.** Αναζητήστε ζητήματα με την ετικέτα [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — αυτά είναι σχεδιασμένα για νεοεισερχόμενους και περιλαμβάνουν το απαραίτητο πλαίσιο για να ξεκινήσετε γρήγορα.
|
|
|
|
2. **Επιλέξτε ένα πεδίο.** Καλές πρώτες συνεισφορές περιλαμβάνουν:
|
|
- Διορθώσεις τυπογραφικών λαθών και τεκμηρίωσης
|
|
- Προσθήκες ή βελτιώσεις δοκιμών (tests)
|
|
- Μικρές διορθώσεις σφαλμάτων με σαφή βήματα αναπαραγωγής
|
|
|
|
3. **Ακολουθήστε τη ροή εργασίας fork → branch → change → test → PR:**
|
|
- Κάντε fork το αποθετήριο και κλωνοποιήστε το δικό σας fork
|
|
- Δημιουργήστε έναν κλάδο δυνατοτήτων (feature branch) (`git checkout -b fix/my-change`)
|
|
- Κάντε τις αλλαγές σας και εκτελέστε `cargo fmt && cargo clippy && cargo test`
|
|
- Ανοίξτε ένα PR προς το `dev` χρησιμοποιώντας το πρότυπο PR
|
|
|
|
4. **Ξεκινήστε με το Track A.** Το ZeroClaw χρησιμοποιεί τρία [επίπεδα συνεργασίας](#επίπεδα-συνεργασίας-βάσει-κινδύνου) (A/B/C) βάσει κινδύνου. Οι συνεισφέροντες για πρώτη φορά θα πρέπει να στοχεύουν στο **Track A** (τεκμηρίωση, δοκιμές, μικροεργασίες) — αυτά απαιτούν ελαφρύτερη αναθεώρηση και είναι η ταχύτερη διαδρομή για την ενσωμάτωση (merge) ενός PR.
|
|
|
|
Εάν κολλήσετε, ανοίξτε ένα draft PR νωρίς και κάντε ερωτήσεις στην περιγραφή.
|
|
|
|
## Ρύθμιση Ανάπτυξης
|
|
|
|
```bash
|
|
# Κλωνοποιήστε το αποθετήριο
|
|
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
|
cd zeroclaw
|
|
|
|
# Ενεργοποιήστε το pre-push hook (εκτελεί fmt, clippy, δοκιμές πριν από κάθε push)
|
|
git config core.hooksPath .githooks
|
|
|
|
# Κατασκευή (Build)
|
|
cargo build
|
|
|
|
# Εκτέλεση δοκιμών (πρέπει να περάσουν όλες)
|
|
cargo test --locked
|
|
|
|
# Μορφοποίηση και έλεγχος (απαιτείται πριν το PR)
|
|
./scripts/ci/rust_quality_gate.sh
|
|
|
|
# Έκδοση release
|
|
cargo build --release --locked
|
|
```
|
|
|
|
### Pre-push hook
|
|
|
|
Το αποθετήριο περιλαμβάνει ένα pre-push hook στο `.githooks/` που επιβάλλει το `./scripts/ci/rust_quality_gate.sh` και το `cargo test --locked` πριν από κάθε push. Ενεργοποιήστε το με την εντολή `git config core.hooksPath .githooks`.
|
|
|
|
## Τοπική Διαχείριση Μυστικών (Απαιτείται)
|
|
|
|
Το ZeroClaw υποστηρίζει κλιμακωτή διαχείριση μυστικών για την τοπική ανάπτυξη και την υγιεινή του CI.
|
|
|
|
### Επιλογές Αποθήκευσης Μυστικών
|
|
|
|
1. **Μεταβλητές περιβάλλοντος** (συνιστάται για τοπική ανάπτυξη)
|
|
- Αντιγράψτε το `.env.example` στο `.env` και συμπληρώστε τις τιμές
|
|
- Τα αρχεία `.env` αγνοούνται από το Git και πρέπει να παραμένουν τοπικά
|
|
|
|
2. **Αρχείο ρυθμίσεων** (`~/.zeroclaw/config.toml`)
|
|
- Μόνιμη ρύθμιση για μακροχρόνια χρήση
|
|
- Όταν `secrets.encrypt = true` (προεπιλογή), οι τιμές κρυπτογραφούνται πριν την αποθήκευση
|
|
|
|
### Κανόνες Επίλυσης κατά την Εκτέλεση
|
|
|
|
Η επίλυση του κλειδιού API ακολουθεί αυτή τη σειρά:
|
|
|
|
1. Ρητό κλειδί που μεταδίδεται από το config/CLI
|
|
2. Μεταβλητές περιβάλλοντος ειδικά για τον πάροχο (`OPENROUTER_API_KEY`, `OPENAI_API_KEY`, κ.λπ.)
|
|
3. Γενικές μεταβλητές περιβάλλοντος (`ZEROCLAW_API_KEY`, `API_KEY`)
|
|
|
|
### Υγιεινή Μυστικών Πριν το Commit (Υποχρεωτικό)
|
|
|
|
Πριν από κάθε commit, επαληθεύστε:
|
|
|
|
- [ ] Δεν έχουν προστεθεί αρχεία `.env` (μόνο το `.env.example` επιτρέπεται)
|
|
- [ ] Δεν υπάρχουν κλειδιά API/tokens στον κώδικα, τις δοκιμές, τα παραδείγματα ή τα μηνύματα commit
|
|
- [ ] Δεν υπάρχουν διαπιστευτήρια σε εξόδους αποσφαλμάτωσης (debug output)
|
|
|
|
## Επίπεδα Συνεργασίας (Βάσει Κινδύνου)
|
|
|
|
| Επίπεδο | Τυπικό πεδίο | Απαιτούμενο βάθος αναθεώρησης |
|
|
|---|---|---|
|
|
| **Track A (Χαμηλός κίνδυνος)** | τεκμηρίωση/δοκιμές, απομονωμένο refactoring | 1 αναθεώρηση από συντηρητή + επιτυχές CI |
|
|
| **Track B (Μεσαίος κίνδυνος)** | αλλαγές συμπεριφοράς παρόχων/καναλιών/μνήμης | 1 αναθεώρηση με γνώση του υποσυστήματος + τεκμηρίωση επαλήθευσης |
|
|
| **Track C (Υψηλός κίνδυνος)** | ασφάλεια, περιβάλλον εκτέλεσης, CI, όρια πρόσβασης | Αναθεώρηση 2 φάσεων + σχέδιο επαναφοράς (rollback) |
|
|
|
|
---
|
|
|
|
**ZeroClaw** — Μηδενική επιβάρυνση. Κανένας συμβιβασμός. 🦀
|