Skip to content

Latest commit

 

History

History
234 lines (139 loc) · 17.8 KB

CONTRIBUTING.md

File metadata and controls

234 lines (139 loc) · 17.8 KB
Raw

Οδηγός συνεισφοράς στο πρότζεκτ Python-Docs-Gr της κοινότητας PyGreece

Eυχαριστούμε πολύ για το ενδιαφέρον σας να συμμετέχετε στη μετάφραση των επίσημων εγγράφων της Python στα Ελληνικά!

Το συγκεκριμένο πρότζεκτ έχει ξεκινήσει από το PyGreece, μια online κοινότητα εθελοντών της Python. Στο συγκεκριμένο repository θα βρείτε την ομάδα εργασίας που είναι υπεύθυνη για το πρότζεκτ. Όλο το περιεχόμενο της μετάφρασης συντηρείται από εθελοντές που συνεισφέρουν το χρόνο και την εργασία τους στην κοινότητα της Python.

Σε περίπτωση που έχετε οποιαδήποτε απορία για το πρότζεκτ, μπορείτε να μας βρείτε με τους εξής τρόπους:

  • Μπορείτε να μπείτε στον discord server του PyGreece (πρόσκληση εδώ: https://discord.gg/evcNPRVCMB)

  • Μπορείτε να μας βρείτε στο linkedin εδώ

Πριν ξεκινήσετε με την πρώτη σας μετάφραση θα θέλαμε να μοιραστούμε κάποιες γενικές οδηγίες.

Περιεχόμενα

  1. Προετοιμασία
  2. Συνεισφορά
    1. Μετάφραση Αρχείου
    2. Αξιολόγηση Μετάφρασης
  3. Λερώστε τα χέρια σας! Μεταφράστε!

Προετοιμασία

Αυτό γίνεται μόνο μία φορά. Σκόπος είναι η δημιουργία ενός προσωπικού αντιγράφου του έργου. Με το συγκεκριμένο fork μπορείτε να κάνετε όσα PR θέλετε.

  1. Για να υποβάλετε μια μετάφραση, πρέπει να έχετε ένα fork του repository, κάνοντας click στο κουμπί fork όπως φαίνεται παρακάτω (για περισσότερες πληροφορίες δείτε εδώ). Αυτό σας επιτρέπει να δημιουργήσετε ένα προσωπικό αντίγραφο του repository για να δουλέψετε και να κάνετε αλλαγές πάνω σε αυτό:

fork

  1. Κάντε clone το repository που μόλις δημιουργήσατε:
git clone [email protected]:<το username σας>/python-docs-gr.git
  1. Μεταβείτε στον φάκελο που δημιουργήθηκε:
cd python-docs-gr/
  1. Προσθέστε το επίσημο repository ως upstream:
git remote add upstream [email protected]:pygreece/python-docs-gr.git
  1. Και πληκτρολογήστε την παρακάτω εντολή για το upstream του repository σας:
git remote set-url --push upstream [email protected]:<your-username>/cpython.git
  1. Τέλος κατεβάστε το περιεχόμενο του cpython submodule πληκτρολογώντας:
git submodule update --init
  1. [Προαιρετικό βήμα] Δημιουργείστε ένα virtual environment και κάντε activate:
python -m venv env
source env/bin/activate   # macOS or Linux
env\Scripts\activate.bat  # Windows
  1. [Προαιρετικό βήμα] Εγκαταστήστε τα requirements:
pip install -r requirements.txt

Συνεισφορά

Έχουμε μια λίστα με issues στο GitHub όπου συντονίζουμε τη δουλειά που γίνεται ή που πρέπει να γίνει ώστε να γίνεται διαχωρισμός αρμοδιοτήτων και διαχείριση της δουλειάς και των απαιτούμενων ενεργειών.

Οι τρόποι συνεισφοράς στο έργο είναι δύο:

Μετάφραση Αρχείου

Μπορείτε να συνεισφέρετε στην μετάφραση ενός αρχείου από αυτά που θα βρείτε στα issues.

Η διαδικασία μετάφρασης ενός αρχείου είναι η εξής:

  • Επιλέξτε οποιοδήποτε από τα Issues που δεν έχουν ανατεθεί σε κάποιο άλλο άτομο.

  • Αφήστε ένα σχόλιο στο Issue λέγοντας ότι θέλετε να συνεισφέρετε, αναλαμβάνοντας το συγκεκριμένο Issue.

  • Περιμένετε έναν διαχειριστή να σας αναθέσει το Issue.

  • Ξεκινήστε τη μετάφραση!

Τα Issues είναι χωρισμένα σε milestones:

To milestone που μπορείτε να συνεισφέρετε είναι το translate_3.12_additional. Άμα είναι η πρώτη σας φορά σε αυτό το έργο ή γενικότερα σε έργο ανοιχτού κώδικα είναι προτιμότερο να αναλάβετε ένα Issue με label good first issue.

Επίσης, για διευκόλυνση, έχουμε κάνει μια κατηγοριοποίηση των Issues με βάση το μέγεθος (γραμμές κώδικα προς μετάφραση). Πιο αναλυτικά:

  • small για αρχεία με λιγότερες από 200 γραμμές
  • medium για αρχεία με λιγότερες από 500 γραμμές
  • large για αρχεία με λιγότερες από 1000 γραμμές
  • xlarge για αρχεία με λιγότερες από 2500 γραμμές
  • god (για τους τολμηρούς) για αρχεία με περισσόρερες από 2500 γραμμές

Αξιολόγηση Μετάφρασης

Μπορείτε να συνεισφέρετε κάνοντας μια αξιολόγηση των ήδη μεταφρασμένων αρχείων, για τυχόν παρατηρήσεις, βελτιώσεις, ελλείψεις ή διορθώσεις στην μετάφραση.

Η διαδικασία είναι:

  • Ανοίξτε ένα Issue

    new_issue

  • Γράψτε στην περιγραφή τις παρατηρήσεις σας.

  • Μέσα από τα σχόλια του Issue θα συζητηθεί η παρατήρηση και το σχόλιο σας.

  • Αν από τη συζήτηση προκύψει ότι απαιτείται κάποια αλλάγη, είναι αρεστό να την αναλάβετε εσείς. Κατ' αυτόν τον τρόπο θα κλείσετε το Issue σας με ένα δικό σας PR.

Λερώστε τα χέρια σας! Μεταφράστε!

Εφόσον σας έχει ανατεθεί ένα αρχείο προς μετάφραση, ήρθε η ώρα να λερώσετε τα χέρια σας και να ξεκινήσετε!

Τα αρχεία που πρέπει να μεταφραστούν είναι αυτά με την κατάληξη .po.

Τα εργαλεία που προτείνουμε να χρησιμοποιήσετε είναι το VScode ή το PoEdit. Για το VScode μια χρήσιμη επέκταση είναι το gettext extension. Αντίθετα το PoEdit χρησιμοποιεί ένα καλύτερο περιβάλλον διεπαφής και δεν απατείται να ασχοληθεί ο χρήστης με τη δομή του αρχείου.

  1. Επιβεβαιώστε ότι είστε στο 3.12 branch (πολύ σημαντικό βήμα για να αποφύγετε να ξεκινήσετε ένα branch από παλαιότερη έκδοση):
git checkout 3.12
  1. Δημιουργείστε ένα branch βασισμένο στο αρχείο που θα δουλέψετε. Για παράδειγμα, εάν δουλέυετε στο αρχείο library/ast.po το όνομα του branch θα μπορούσε να είναι:
git checkout -b translate-library-ast

              ή

git checkout -b library-set

              ή

git checkout -b ft/library-set

  1. Αφού έχετε διαλέξει το αρχείο σας, ξεκινήστε την μετάφραση στο IDE της επιλογής σας. Επίσης μπορείτε να χρησιμοποιήσετε εργαλεία για την σωστή μετάφραση προτάσεων, φράσεων ή λέξεων.

  2. Εφόσον έχετε ολοκληρώσει τη μετάφρασή σας είναι απαραίτητο να χρησιμοποιήσετε τις εντολές που αναφέρονται παρακάτω προκειμένου να γίνει μορφοποίηση του αρχείου για να έχει μια σωστή δομή καθώς και να γίνει ορθογραφικός έλεγχος.

    1. powrap: έλεγχος και μορφοποίηση της δομής του αρχείου. Μπορείτε να χρησιμοποιήσετε το ακόλουθο script.

      powrap <φάκελος>/<όνομα_του_αρχείου>.po

      Εάν είστε χρήστης των windows μπορείτε να δείτε περισσότερες πληροφορίες εδώ.

    2. popspell: ορθογραφικός έλεγχος του αρχείου pospell. Μπορείτε να χρησιμοποιήσετε το ακόλουθο script.

      python scripts/check_spelling.py <φάκελος>/<όνομα_του_αρχείου>.po

      Εάν κάποια από τις λέξεις δεν είναι αναγνωρισμένη από το script προσθέστε την στο dictionary και επαναλάβετε.

    3. pre-commit: ετοιμάζει και κάνει τις απαραίτητες διαδικασίες προκειμένου το αρχείο να περάσει επιτυχώς τους ελέγχους για την προσάρτισή του. Μπορείτε να χρησιμοποιήσετε το ακόλουθο script.

      pre-commit run --all-files

      Πιο αναλυτικά το παραπάνω script κάνει:

      • τη διαδικασία του powrap
      • ορθογραφικό έλεγχο
      • μορφοποίηση του λεξικού (Αλφαβητική ταξινόμηση και αφαίρεση διπλότυπων)

  3. Μετά από την ολοκλήρωση της μετάφρασης μην ξεχάσετε να βάλετε τα στοιχεία σας στο:

metadata

Στο Language-Team metadata γράφετε: "Language-Team: PyGreece <[email protected]>\n"

  1. Όταν ολοκληρώσετε την μετάφραση σας, πρέπει να αποθηκεύσετε τις αλλαγές σας και να κάνετε push στο GitHub (Μην ξεχάσετε να προσθέσετε το όνομά σας στο αρχείο TRANSLATORS). Για παράδειγμα εάν εργαζόσασταν στο αρχείο library/ast.po τα βήματα θα ήταν:
git add library/ast.po
git commit -m 'Translate file library/ast.po'
git push origin translate-library-ast
  1. Έπειτα μπορείτε να ανοίξετε ένα Pull Request προκειμένου να εξεταστεί/ελεγχθεί η συνεισφορά σας, να γίνουν κάποια σχόλια και εν τέλει να προσαρτηθεί στο βασικό repository. Εφόσον έχετε κάνει push το branch σας θα δείτε κάτι όπως παρακάτω:

pr

Πατώντας το κουμπί θα μεταβείτε στην οθόνη για να βάλετε τις πληροφορίες του συγκεκριμένου Pull Request, και κάνοντας click στο κουμπί Create pull request θα δημιουργηθεί το PR.

pr_descrtiption

Μπράβο! Ανεβάσατε το πρώτο σας PR. Τώρα απλώς περιμένετε να το αξιολογήσουν οι διαχειριστές, και έχετε στο νου σας ότι μπορεί να σας ζητήσουν κάποιες αλλαγές.

Περιμένετε να σας κάνουν αποδοχή το PR σας.

🎉🎉ΤΕΛΟΣ🎉🎉

Συγχαρητήρια, συνεισφέρατε στο έργο και πλέον είστε μέλος του μεγάλου εγχειρήματος της μετάφρασης.

Γενικές Οδηγίες

  • Σε πολλές περιπτώσεις το καλύτερο κριτήριο είναι να σκεφτούμε το λεξιλόγιο που χρησιμοποιούμε όταν εξηγούμε σε άλλο άτομο ή στη δουλειά. Σε πολλές περιπτώσεις, η αγγλική είναι πολύ καλύτερη αν θελετε πχ. να πείτε "git join".

  • Θα έχετε πάντα διαθέσιμο ένα preview αυτού που προτείνετε, καθώς και reviewers να σας βοηθήσουν.

  • Η διαδικασιά του review είναι επίσης πολύ σημαντική. Αν έχετε ελεύθερο χρόνο θα ήταν το ίδιο σημαντικό να συνεισφέρετε κάνοντας review σε ήδη ανοιχτά Pull Requests (περισσότερες πληροφορίες εδώ).

  • Τα επίσημα έγγραφα της Python είναι άπειρα! Αν αντιμετωπίσετε εμπόδια, μπορείτε πάντα να επισημάνετε το κείμενο ως "ασαφές" ή να το αναθεωρήσετε στο μέλλον. Μην σπαταλάτε ώρες αναζητώντας την τέλεια λέξη.

  • Δεν πρέπει να μεταφράσετε το περιεχόμενο των :ref:..., :term:..., :dfn:..., κ.λπ.

  • Εάν πρέπει να χρησιμοποιήσετε αγγλικές λέξεις, θα πρέπει να τις βάλετε με πλάγιους χαρακτήρες (περιτριγυρισμένοι με αστερίσκους).

  • Μπορείτε να συμβουλευτείτε τις Συχνές Ερωτήσεις για να διαβάσετε για γνωστά ζητήματα.

  • Εάν μεταφράσετε έναν τίτλο που είναι σύνδεσμος, μεταφράστε και τον σύνδεσμο (για παράδειγμα ένα άρθρο στη Wikipedia). Σε περίπτωση που δεν υπάρχει μετάφραση του άρθρου στη Wikipedia, αφήστε τον τίτλο αμετάφραστο.

  • Εάν έχετε μια ερώτηση σχετικά με μια λέξη ή όρο, γράψτε την όπως σας φαίνεται καλύτερα και σημειώστε αυτήν την παράγραφο ως "Needs Work". Επίσης, γράψτε ένα σχόλιο εξηγώντας για ποιον όρο σε αυτήν την παράγραφο δεν ήσασταν σίγουροι.

  • Συνιστούμε να ανοίξετε ένα Pull Request ακόμα κι αν είναι σε μορφή draft (επισημασμένο ως πρόχειρο) από τις πρώτες προσπάθειες της μετάφρασης του αρχείου σας. Με αυτόν τον τρόπο, μπορείτε να λάβετε σχόλια από την αρχή που μπορείτε να εφαρμόσετε στην υπόλοιπη μετάφραση.

  • Τελευταίο αλλά όχι λιγότερο σημαντικό, διασκεδάστε και βασιστείτε στη βοήθεια όλων. Περιμένουμε τα μηνύματα σας στο discord, εδώ ή στο linkedin. Ευχαριστούμε!

  • Για τους contributors που χρησιμοποιούν το vscode ως IDE ένα πολύ χρήσιμο add-on για τα .po αρχεία είναι το gettext extension.