Κάνοντας το πρώτο σας PR (pull request=αίτημα έλξης)

Αυτή η περιγραφή αφορά μόνο την επεξεργασία της αγγλικής τεκμηρίωσης. Εάν θέλετε να μεταφράσετε σε άλλες γλώσσες (ευχαριστούμε), χρησιμοποιήστε crowdin .

Για τυχόν ερωτήσεις, σχόλια ή νέες ιδέες, μπορείτε να επικοινωνήσετε με την ομάδα τεκμηρίωσης μέσω ηλεκτρονικού ταχυδρομείου (wiki@androidaps.org). Κάνοντας ένα PR δεν είναι δύσκολο, αλλά μπορούμε να σας βοηθήσουμε να επεξεργαστείτε την τεκμηρίωση.

Κάποια στιγμή θα σας προτείνουμε να κάνετε ένα PR. Το PR είναι σύντομογραφία για το pull request (αίτημα έλξης) και είναι ένας τρόπος προσθήκης ή επεξεργασίας πληροφοριών που είναι αποθηκευμένες στο GitHub. Δεν είναι πραγματικά πολύ δύσκολο να το κάνεις και είναι ένας πολύ καλός τρόπος να συμβάλεις. Αυτή η τεκμηρίωση είναι εδώ επειδή άνθρωποι σαν εσάς έκαναν PRs. Μην ανησυχείτε αν κάνετε κάποιο λάθος ή επεξεργαστείτε με κάποιο τρόπο τα λάθος έγγραφα. Υπάρχει πάντα μια διαδικασία αναθεώρησης πριν από τη συγχώνευση των αλλαγών στην “επίσημη” αποθήκη τεκμηρίωσης AndroidAPS. Δεν μπορείτε να χαλάσετε τα πρωτότυπα από τυχόν ατυχήματα στη διαδικασία PR. Η γενική διαδικασία είναι:

  • Κάντε τροποποιήσεις και βελτιώσεις σε κώδικα ή τεκμηρίωση με επεξεργασία του υπάρχοντος περιεχομένου.
  • Ελέγξτε ξανά ότι οι επεξεργασίες σας φαίνονται καλές σε εσάς.
  • Δημιουργήστε μερικές σημειώσεις για το τι άλλαξε, ώστε οι άνθρωποι να κατανοήσουν τις αλλαγές.
  • Δημιουργήστε ένα αίτημα έλξης, το οποίο ζητά από τους διαχειριστές να χρησιμοποιήσουν τις αλλαγές σας.
  • Θα κάνουν μια ανασκόπηση και (1) θα συγχωνεύσουν τις αλλαγές σας, (2) θα σας σχολιάσουν τις αλλαγές σας ή (3) θα ξεκινήσουν ένα νέο έγγραφο με τις αλλαγές σας.

(Πλευρική σημείωση: Εάν είστε τύπος της οπτικής επαφής, υπάρχει ένα βίντεο στο YouTube εδώ που δείχνει τη ροή εργασίας PR)

Για παράδειγμα, πρόκειται να κάνουμε μια επεξεργασία στο AndroidAPSdocs. Αυτό δεν χρειάζεται να γίνει στο περιβάλλον linux στην εξέδρα σας. Αυτό μπορεί να γίνει σε οποιοδήποτε υπολογιστή με Windows, Mac, κλπ. (οποιοσδήποτε υπολογιστής με πρόσβαση στο Internet).

  1. Μεταβείτε στη διεύθυνση https://github.com/openaps/AndroidAPSdocs και χτυπήστε το Πιρούνι στην επάνω δεξιά γωνία για να δημιουργήσετε το δικό σας αντίγραφο του αποθετηρίου. Fork repo
  2. Μεταβείτε στη διεύθυνση http://androidaps.readthedocs.io/en/latest/Getting-Started/Safety-first.html ή παρόμοια και μεταβείτε στη σελίδα που θέλετε να επεξεργαστείτε. Κάντε κλικ στο μαύρο πλαίσιο στο κάτω αριστερά μέρος της σελίδας με την πράσινη λέξη “v: latest” ή παρόμοια. Στο αναδυόμενο παράθυρο που εμφανίζεται, κάντε κλικ στη λέξη “επεξεργασία” για επεξεργασία στο GitHub.edit doc Ή μπορείτε να κάνετε κλικ στο σύνδεσμο “Επεξεργασία σε Github” στην επάνω δεξιά γωνία και, στη συνέχεια, κάντε κλικ στο εικονίδιο με το μολύβι που εμφανίζεται στην επάνω μπάρα των περιεχομένων της σελίδας για επεξεργασία. RTD io
  3. ή η μία ή η άλλη από τις επιλογές στο Βήμα 2 θα δημιουργήσει ένα νέο υποκατάστημα στην αποθήκη σας όπου θα αποθηκευτούν οι επεξεργασίες σας. Πραγματοποιήστε τις επεξεργασίες σας στο αρχείο. Επεξεργασία κλάδου
  4. Εργάζεστε στην καρτέλα “<> Επεξεργασία αρχείου”. Επιλέξτε την καρτέλα “Προεπισκόπηση αλλαγών” για μια νέα εμφάνιση, για να βεβαιωθείτε ότι όλα όσα αλλάξατε μοιάζουν με αυτά που σήμαινε (typos sic.). Αν βλέπετε μια απαραίτητη βελτίωση, επιστρέψτε στην καρτέλα επεξεργασίας για να κάνετε περισσότερες βελτιώσεις. Έχετε υπόψη σας ότι χρησιμοποιούμε διαφορετικές επεκτάσεις αρχείων: .rst (ReStructuredText) και .md (Markdown) και η σύνταξη ποικίλει λίγο μεταξύ των δύο. λειτουργία προεπισκόπησης
  5. Όταν τελειώσετε τις επεξεργασίες σας, μεταβείτε στο κάτω μέρος της σελίδας. Στο πλαίσιο στο κάτω μέρος, δώστε τα σχόλιά σας στο πεδίο κειμένου που αναφέρει “Προσθέστε μια προαιρετική εκτεταμένη περιγραφή...”. Ο προεπιλεγμένος τίτλος έχει το όνομα του αρχείου. Προσπαθήστε να συμπεριλάβετε μια πρόταση που εξηγεί τον **λόγο ** για την αλλαγή. Συσχέτιση με την αιτία που έγινε αυτό βοηθά τους αναθεωρητές να καταλάβουν τι προσπαθείτε να κάνετε με το PR. παρέθεσε σχόλια
  6. Κάντε κλικ στο πράσινο κουμπί “Προτεινόμενες αλλαγές αρχείων” ή “Ανάκτηση αλλαγών”. Στη σελίδα που εμφανίζεται, κάντε κλικ στην επιλογή “Δημιουργία αιτήματος έλξης” και, στη συνέχεια, στην επόμενη σελίδα, κάντε κλικ στην επιλογή “Δημιουργία αιτήματος έλξης”. δημιουργήστε αίτημα έλξης
  7. Αυτό ολοκληρώνει το άνοιγμα ενός αιτήματος έλξης, PR. Το GitHub εκχωρεί στον PR έναν αριθμό που βρίσκεται μετά τον τίτλο και ένα σήμα κατατεθέν. Επιστρέψτε σε αυτήν τη σελίδα για να ελέγξετε για ανατροφοδότηση (ή, αν έχετε ειδοποιήσει μέσω ηλεκτρονικού ταχυδρομείου μέσω του Github, θα λάβετε μηνύματα ηλεκτρονικού ταχυδρομείου που θα σας ειδοποιούν για οποιαδήποτε δραστηριότητα στο PR). Η επεξεργασία θα είναι τώρα σε μια λίστα PR που η ομάδα θα εξετάσει και ενδεχομένως να δώσει σχόλια πριν από τη δέσμευση στην κύρια τεκμηρίωση για το AndroidAPS! Εάν θέλετε να ελέγξετε την πρόοδο του PR, μπορείτε να κάνετε κλικ στο λογότυπο της καμπάνιας στην επάνω δεξιά γωνία του λογαριασμού σας GitHub και να δείτε όλα τα PR σας. Παρακολούθηση PR

Συγχαρητήρια, κάνατε την πρώτη σας συμβολή!

PS, το πιρούνι και το παρακλάδι σας θα εξακολουθούν να κάθονται στο δικό σας προσωπικό λογαριασμό GitHub. Αφού λάβετε μια ειδοποίηση ότι το PR σας έχει συγχωνευθεί, μπορείτε να διαγράψετε το παρακλάδι σας αν έχετε τελειώσει με αυτό (η περιοχή ειδοποιήσεων του βήματος 8 θα παράσχει έναν σύνδεσμο για να διαγράψει το υποκατάστημα μόλις κλείσει ή συγχωνευθεί). Για μελλοντικές επεξεργασίες, εάν ακολουθήσετε αυτή τη διαδικασία, οι επεξεργασίες θα ξεκινούν πάντα με μια ενημερωμένη έκδοση των αποθετηρίων του AndroidAPSdocs. Εάν επιλέξετε να χρησιμοποιήσετε μια άλλη μέθοδο για να ξεκινήσετε μια αίτηση PR (π.χ. επεξεργασία που ξεκινάει από το κύριο παρακλάδι του repos σας ως σημείο εκκίνησης), θα πρέπει να διασφαλίσετε ότι το repo σας είναι ενημερωμένο κάνοντας πρώτα μια σύγκριση και συγχώνευση σε τυχόν ενημερώσεις που έχουν συμβεί από την τελευταία ενημέρωση του πιρουνιού σας. Εφόσον οι άνθρωποι τείνουν να ξεχνούν να ενημερώσουν τα repos τους, συνιστούμε να χρησιμοποιήσετε τη διαδικασία PR που περιγράφεται παραπάνω, μέχρι να εξοικειωθείτε με την εκτέλεση “συγκρίσεων”.

Σύνθετες συμβουλές για την προσθήκη εσωτερικών συνδέσεων

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

Σε αρχεία που τελειώνουν με: **.md **

  • [text] (../ Usage / Test.md) θα ορίσει μια εσωτερική υπερσύνδεση ένα κατάλογο προς τα πάνω από εκεί που βρίσκεστε και στη συνέχεια στον υποκατάλογο / Χρήση. Ο τερματισμός του αρχείου προορισμού πρέπει να είναι .md ή .rst (όχι .html)
  • [text] (/ Usage / Test.md) θα ορίσει μια εσωτερική υπερσύνδεση από εκεί που βρίσκεστε στο / Usage. Ο τερματισμός του αρχείου προορισμού πρέπει να είναι .md ή .rst (όχι .html)

Για να ορίσετε τη σύνδεση σε ** άγκυρα ** (δηλαδή μια επικεφαλίδα) πρέπει να παραλείψετε την επέκταση αρχείου

  • [text](../Usage/Test#anchor) αντί για [text](../Usage/Test.md#anchor)

Σε αρχεία που λήγουν με: **.rst **

  • `Text <../Usage/Test.hmtl>`_ θα ορίσει έναν υπερσύνδεσμο έναν κατάλογο απο πάνω από εκεί που βρίσκεστε και στη συνέχεια στον υποκατάλογο / Χρήση. Το τέλος στο αρχείο προορισμού πρέπει να είναι .html. Εκτός του ότι είναι σε toctree. Στη συνέχεια, θα πρέπει να το γράψετε σαν αυτό: Text <../Usage/Test.md> με .md ή .rst (όχι .html).
  • Text <./Usage/Test.md> θα θέσει μια υπερ-σύνδεση από το σημείο στο οποίο βρίσκεστε /Usage.

Προηγμένες συμβουλές για την προσθήκη πολλών εικόνων στην τεκμηρίωση

Αν σχεδιάζετε να κάνετε πολλές αλλαγές, συμπεριλαμβανομένης της προσθήκης εικόνων που θα σας βοηθήσουν να απεικονίσετε τμήματα της τεκμηρίωσης (ευχαριστούμε!), Ίσως θελήσετε να ακολουθήσετε την ακόλουθη προσέγγιση:

  • Καθώς πηγαίνετε και αποθηκεύετε στιγμιότυπα οθόνης, μετονομάστε τα στιγμιότυπα οθόνης σε ένα περιγραφικό όνομα - αλλά προσπαθήστε να μην χρησιμοποιήσετε κενά όπως αυτό προκαλεί σύγχυση στον Github. Αντ ‘αυτού, χρησιμοποιήστε τις υπογραμμίσεις. Π.χ. Example_batch_images_upload.png αντί για “Example batch images upload.png”.

  • Μπορείτε να ανεβάσετε τις εικόνες σε παρτίδες εύκολα με:

    1. Πλοηγηθείτε στο φάκελο εικόνων (https://github.com/openaps/AndroidAPSdocs/tree/master/docs/EN/images - αλλά βεβαιωθείτε ότι βρίσκεστε στο διανομέα πιρούνι / αντίγραφο του φακέλου για να το κάνετε αυτό ( αντικαταστήστε “openaps” στη διεύθυνση URL με το όνομα χρήστη github)).
    2. Κάντε κλικ στην επάνω δεξιά γωνία όπου αναγράφεται “Αποστολή αρχείων”
    3. Σύρετε και αποθέστε τις εικόνες σας στην οθόνη
    4. Αναθέστε τα στο υποκατάστημά σας
    5. Τώρα, μπορείτε να αναζητήσετε τη διεύθυνση URL / σχετική διαδρομή κάθε αρχείου και να την χρησιμοποιήσετε για να αναφερθείτε κατά την προσθήκη εικόνων σε μια σελίδα της τεκμηρίωσης.
    6. Για να δείτε παραδείγματα για τον τρόπο προσθήκης των εικόνων, μπορείτε να δείτε τον “ακατέργαστο” κώδικα μιας σελίδας για να δείτε ένα παράδειγμα από μια σελίδα που έχει ήδη ενσωματώσει τις εικόνες με επιτυχία. Το κύριο πράγμα είναι να έχουμε μια περιγραφή απλού κειμένου, ακολουθούμενη από μια σύνδεση με μια σχετική διαδρομή προς την εικόνα, όπως αυτή: ! [Παράδειγμα αποστολής εικόνων σε παρτίδες] (../ images / Example_batch_images_upload.png)

    (Αυτός ο κώδικας είναι ακριβώς πώς θα ενσωματωθεί η εικόνα παρακάτω)

Παράδειγμα φόρτωσης εικόνων σε παρτίδες

  1. Μετά την προσθήκη εικόνων ή την πραγματοποίηση προσαρμογών, μπορείτε να υποβάλετε ένα PR στον κύριο κλάδο του AndroidAPSdocs.