Θέλεις να συνεισφέρεις στο ES4X ή να αναφέρεις κάποιο πρόβλημα; Πρώτα διάβασε τον παρακάτω οδηγό.

# Τυπικές περιστάσεις για αναφορά προβλήματος

# Ερώτηση ή κάποιο πρόβλημα;

Για κάποια απλή ερώτηση, δε χρειάζεται να ανοίξεις κάποιο issue, μπορείς απλά να μας στείλεις στο gitter.im (opens new window).

# Βρήκες κάποιο bug?

Αν βρήκες κάποιο bug στον πηγαίο κώδικα, μπορείς να το αναφέρεις εδώ (opens new window) στο GitHub repository μας. Ακόμα καλύτερα μπορείς να συνεισφέρεις εσύ στην αντιμετώπιση του προβλήματος με ένα Pull Request. Πρώτα όμως διάβασε τις οδηγίες συνεισφοράς.

# Πρόταση για νέο feature?

Μπορείς να αιτηθείς ενα νέο feature υποβάλλοντας ένα issue στο GitHub Repository μας. Αν θέλεις να το υλοποιήσεις, πρέπει πρώτα να προτείνεις επίσης και τη λύση, για να είμαστε σίγουροι οτι είναι χρήσιμο για όλους. Υπάρχουν δύο κατηγορίες προτάσεων:

  • Για ενα major feature, πρώτα άνοιξε ένα issue μαζί με μια περίληψη του feature για να συζητηθεί. Αυτό θα μας βοηθήσει να αποφύγουμε διπλή δουλειά και παράλληλα να βοηθήσουμε εσένα όσο καλύτερα γίνεται.

  • Μικρά features and bugs μπορούν απευθείας να υποβληθούν σαν Pull Request χωρίς ανοίγοντας κάποιο νέο issue. Ωστόσο, δεν εγγυόμαστε οτι το feature θα βρεθεί στο master, γιατί κοιτάμε αν όντως προσθέτει αξία στον υπάρχον κώδικα.

# Οδηγίες συνεισφοράς

# Υποβάλλοντας νέο issue

Πριν υποβάλεις ένα νέο issue, κοίτα μήπως υπάρχει ήδη κάποιο issue για το πρόβλημα σου. Αυτό ίσως σε βοηθήσει να βρεις κάποια workarounds στο πρόβλημα σου.

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

Δυστυχώς, αν δεν υπάρχει κάποιο σενάριο, και δε λάβουμε απάντηση απο εσένα, πολλή πιθανόν να κλείσουμε το issue.

# Υποβάλλοντας ένα Pull Request (PR)

Πρώτα κοίτα αν υπάρχει κάποιο ανοιχτό ή κλειστό PR το οποίο διορθώνει το ίδιο πρόβλημα.

Αν δε βαρείς κάποιο μπορείς να συνεχίσεις.

  1. Development: Κάνε Fork το repository, κάνε τις αλλαγές σου σε ένα διαφορετικό branch όπου τα commits θα είναι κατανοητά.

  2. Build: Πριν ανοίξεις κάποιο pull request, "χτίσε" το project. Αυτό είναι απαραίτητο για να γίνει δεκτό το PR σου. Έτσι, είμαστε σίγουροι οτι το project λειτουργεί.

  3. Pull Request: Αφού "χτίσεις" το project, κάνε commit αυτό που παρήγαγε. Κάνε push το branch σου και άνοιξε ένα PR για το es4x:develop. Σε περίπτωση που προτείνουμε κάποιες αλλαγές, κάνε τις αλλαγές, στο branch σου και αυτές οι αλλαγές αυτομάτως θα ενημερώσουν το PR.

Άμα το PR έγινε δεκτό, μπορείς να διαγράψεις το branch σου και να κάνεις pull τις αλλαγές απο το main(upstream) repository.

# Building the world

Για να "χτίσεις" το world θα χρειαστείς κάποια εργαλεία στον υπολογιστή σου:

Αμά έχεις ήδη εγκατεστημένο το GraalVM και το Maven δε χρειάζεσαι το Node.js και το NPM αν και η node που βρίσκεται στο GraalVM έχεις κάποια θέματα επιδόσεων σε κάποιες npm βιβλιοθήκες όπως η TypeScript Compiler.

# Modules

Τα παρακάτω project απαρτίζονται από διάφορα modules/components:

  1. es4x (opens new window) Ο κύριος κώδικας java που εκκινεί το GraalJS και το Vert.x.
  2. pm (opens new window) Το πρόγραμμα διαχείρισης πακέτων
  3. codegen (opens new window) Η βιβλιοθήκη που θα δημιουργήσει τα αντίστοιχα πακέτα npm για το vert.x
  4. generator (opens new window) Μaven script δημιουργεί το πλήρες πακέτο npm για ένα vert.x module
  5. docs (opens new window) Ο φάκελος που βλέπεις τώρα

# Χτίζοντας το Java κομμάτι

Για να χτίσεις το java κομμάτι είναι αρκετά εύκολο:

mvn -Pcodegen install

Χρησιμοποίησε την παράμετρο codegen άν θες να δημιουργήσεις και τα npm modules. Σε άλλη περίπτωση:

  • es4x
  • pm
  • codegen

θα χτιστούν

# Δημοσίευση των NPM modules

Κατά την διάρκεια του development, ίσως χρειαστει να δημοσιεύσεις σε κάποιο τοπικό NPM registry. Σε αύτη την περίπτωση μπορείς να χρησιμοποιήσεις το verdaccio (opens new window).

npm install -g verdaccio

Αφού το έχεις εγκαταστήσει ακολούθα τις οδηγίες για να συνδεθείς στο registry.

npm adduser --registry "http://localhost:4873"

Τα πακέτα έχουν όριο στο μέγεθος

Το πακέτο pm είναι σχετικά μεγάλο και για να το διαχειριστεί το verdaccio πρέπει να ενημερώσεις το default config και να κάνεις restart.

Επεξεργάσου το αρχείο ~/.config/verdaccio/config.yaml και πρόσθεσε την παρακάτω γραμμή:

# max package size
max_body_size: 100mb

Τώρα μπορείς να δημοσιεύσεις τα npm πακέτα τοπικά:

cd generator
mvn -Dnpm-registry="http://localhost:4873" \
    clean \
    generate-sources \
    exec:[email protected]

API docs

Αν θέλει να δημιουργήσεις αυτόματα API docs, χρειάζεσαι κάποια εργαλεία ακόμα.

# εγκατέστησε το API doc generator
npm install -g typedoc
# δημοσίευσε στο verdaccio and και δημιουργήσε τα docs στο docs φάκελο
cd generator
mvn -Dnpm-registry="http://localhost:4873" \
    clean \
    generate-sources \
    exec:[email protected] \
    exec:[email protected]

# Δημοσίευσε το PM στο npm

Για ευκολία, το pm μπορεί επίσης να δημοσιευθεί μητρώο NPM:

cd pm
mvn package
./publish.sh local

Αυτό θα δημιουργήσει το "fat jar" και το τελικό script θα το μετατρέψει σε πακέτο npm και θα το δημοσιεύσει στην τοπική εγκατάσταση verdaccio.