[ English | français | Deutsch | русский | Indonesia | English (United Kingdom) | 한국어 (대한민국) ]

Aturan kode

Pedoman Umum untuk Mengirimkan Kode

  • Tulis pesan komit yang baik. Kami mengikuti panduan OpenStack "Git Commit Good Practice" . jika Anda memiliki pertanyaan tentang cara menulis pesan komit yang baik, silakan tinjau dokumentasi OpenStack hulu.

  • Perubahan pada proyek harus diserahkan untuk ditinjau melalui alat Gerrit, mengikuti workflow documented here.

  • Permintaan penarikan yang diajukan melalui GitHub akan diabaikan dan ditutup tanpa memperhatikan.

  • Patch harus difokuskan pada penyelesaian satu masalah pada satu waktu. Jika ulasan terlalu rumit atau umumnya besar, komit awal akan menerima "-2" dan kontributor akan diminta untuk membagi patch di beberapa ulasan. Dalam hal penambahan fitur yang kompleks, desain dan implementasi fitur harus dilakukan sedemikian rupa sehingga dapat diajukan dalam beberapa patch menggunakan dependensi. Menggunakan perubahan dependen harus selalu bertujuan untuk menghasilkan membangun kerja di seluruh rantai ketergantungan. Dokumentasi juga tersedia untuk advanced gerrit usage.

  • Semua set patch harus mematuhi Panduan Style Ansible yang tercantum di sini dan juga mematuhi Ansible best practices bila memungkinkan.

  • Semua perubahan harus secara jelas tercantum dalam pesan komit, dengan id/blueprint bug terkait bersama dengan informasi tambahan apa pun yang berlaku.

  • Pekerjaan refactoring tidak boleh menyertakan fitur "rider" tambahan. Fitur yang mungkin berkaitan dengan sesuatu yang difaktorkan ulang harus dimunculkan sebagai masalah dan diajukan dalam patch sebelum atau sesudahnya.

  • Fitur-fitur baru, memecah perubahan dan tambalan lain dari catatan harus menyertakan catatan rilis yang dihasilkan menggunakan the reno tool. Silakan lihat Documentation and Release Note Guidelines untuk informasi lebih lanjut.

  • Semua patch termasuk kode, dokumentasi, dan catatan rilis harus dibuat dan diuji secara lokal dengan suite pengujian yang sesuai sebelum mengirimkan untuk ditinjau. Lihat Development and Testing untuk informasi lebih lanjut.

Pedoman Dokumentasi dan Catatan Rilis

Dokumentasi adalah bagian penting untuk memastikan bahwa penyebar OpenStack-Ansible diberi informasi tentang:

  • Cara menggunakan perkakas proyek secara efektif untuk menyebarkan OpenStack.

  • Bagaimana menerapkan konfigurasi yang tepat untuk memenuhi kebutuhan kasus penggunaan khusus mereka.

  • Perubahan dalam proyek dari waktu ke waktu yang dapat mempengaruhi penyebaran yang ada.

Untuk memenuhi kebutuhan ini, pengembang harus menyerahkan code comments, dokumentasi (lihat juga documentation locations section) dan release notes dengan pengiriman kode apa pun .

Semua bentuk dokumentasi harus mematuhi pedoman yang disediakan dalam OpenStack Documentation Contributor Guide, dengan referensi khusus ke bagian-bagian berikut:

  • Gaya menulis

  • Konvensi pemformatan RST

Komentar Kode

Komentar kode untuk variabel harus digunakan untuk menjelaskan tujuan variabel. Ini sangat penting untuk file peran default karena file tersebut dimasukkan kata demi kata dalam dokumentasi peran. Jika ada variabel opsional, variabel dan penjelasan tentang apa yang digunakan untuk itu harus ditambahkan ke file default.

Komentar kode untuk skrip bash/python harus memberikan panduan untuk tujuan kode. Ini penting untuk memberikan konteks bagi pengulas sebelum patch bergabung, dan untuk modifikasi selanjutnya mengingatkan para kontributor apa tujuannya dan mengapa itu dilakukan seperti itu.

Lokasi dokumentasi

OpenStack-Ansible memiliki berbagai bentuk dokumentasi dengan maksud berbeda.

The Deployment Guide bermaksud untuk membantu para deployer menggunakan OpenStack-Ansible untuk pertama kalinya.

The User Guide bermaksud untuk memberikan kisah pengguna tentang cara melakukan hal-hal spesifik dengan OpenStack-Ansible.

The Operations Guide memberikan bantuan tentang cara mengelola dan mengoperasikan OpenStack-Ansible.

Informasi teknis mendalam terletak di OpenStack-Ansible Reference.

Dokumentasi peran (misalnya, dokumentasi peran keystone) bermaksud untuk menjelaskan semua opsi yang tersedia untuk peran dan bagaimana menerapkan persyaratan yang lebih maju. Untuk mengurangi duplikasi, dokumentasi peran secara langsung menyertakan file variabel default peran yang mencakup komentar yang menjelaskan tujuan variabel. Dokumentasi lama untuk peran harus kurang fokus pada menjelaskan variabel dan lebih pada menjelaskan bagaimana menerapkan kasus penggunaan lanjutan.

Dokumentasi peran harus menyertakan uraian tentang infrastruktur wajib (Sebagai contoh: diperlukan database dan antrian pesan), variabel (Misalnya: nama basis data dan kredensial) dan nama grup (Misalnya: Peran mengharapkan grup bernama foo_all untuk hadir dan mengharapkan host untuk menjadi anggota itu) agar eksekusi peran berhasil.

Bila memungkinkan, dokumentasi di OpenStack-Ansible harus menghindari mencoba menjelaskan konsep OpenStack. Penjelasan-penjelasan itu termasuk dalam Manual OpenStack atau dokumentasi layanan dan dokumentasi OpenStack-Ansible harus terhubung ke dokumen-dokumen itu jika tersedia, daripada menduplikasi konten mereka.

Catatan Rilis

Catatan rilis dihasilkan menggunakan the reno tool. Catatan rilis harus ditulis dengan pedoman berikut dalam pikiran:

  • Setiap item daftar harus masuk akal untuk dibaca tanpa konteks tambalan atau repositori patch sedang diajukan. Alasan untuk ini adalah bahwa semua catatan rilis dikonsolidasikan dan disajikan dalam daftar panjang tanpa referensi ke patch sumber atau konteks repositori.

  • Setiap note harus singkat dan to the point. Cobalah untuk menghindari note multi-paragraf. Untuk fitur, note biasanya merujuk ke dokumentasi untuk detail lebih lanjut. Untuk perbaikan bug, note dapat merujuk ke bug terdaftar untuk detail lebih lanjut.

Dalam kebanyakan kasus hanya bagian berikut yang harus digunakan untuk catatan rilis baru yang dikirimkan dengan patch:

  • features: Ini harus memberi tahu penyebar secara singkat tentang fitur baru dan harus menjelaskan cara menggunakannya dengan merujuk variabel yang akan diatur atau dengan merujuk pada dokumentasi.

  • issues: Ini harus memberi tahu penyebar tentang masalah yang diketahui. Ini dapat digunakan saat memperbaiki masalah dan ingin memberi tahu penyebar tentang solusi yang dapat digunakan untuk versi sebelum yang berisi patch yang memperbaiki masalah. Catatan masalah harus secara khusus menyebutkan versi OpenStack-Ansible apa yang dipengaruhi oleh masalah ini.

  • upgrade: Ini harus memberi tahu penyebar tentang perubahan yang dapat memengaruhi mereka saat memutakhirkan dari versi mayor atau minor sebelumnya. Biasanya, catatan ini akan menjelaskan perubahan nilai variabel default atau variabel yang telah dihapus.

  • deprecations: Jika suatu variabel telah ditinggalkan (idealnya menggunakan filter penghentian), maka itu harus dikomunikasikan melalui catatan di bagian ini. Perhatikan bahwa jika suatu variabel telah dihapus seluruhnya maka itu tidak ditinggalkan dan penghapusan harus dicatat di bagian upgrade .

Mengirimkan spesifikasi

Dengan mengajukan draf spesifikasi, Anda dapat membantu komunitas OpenStack-Ansible melacak peran atau perubahan besar apa yang sedang dikembangkan, dan mungkin menghubungkan Anda dengan orang lain yang mungkin tertarik dan dapat membantu Anda dalam proses tersebut.

Repository spesifikasi kami mengikuti pedoman OpenStack dan OpenStack-Ansible yang biasa untuk mengirim kode.

Namun, untuk membantu Anda dalam penulisan spesifikasi, kami memiliki template spesifikasi yang dapat disalin ke folder nama rilis terbaru. Ganti nama dan edit untuk kebutuhan Anda.

Panduan Style Ansible

Pemformatan YAML

Saat membuat tugas dan peran lain untuk digunakan di Ansible, buat tugas menggunakan format kamus YAML.

Contoh format kamus YAML:

- name: The name of the tasks
   module_name:
     thing1: "some-stuff"
     thing2: "some-other-stuff"
   tags:
     - some-tag
     - some-other-tag

Contoh apa yang NOT harus dilakukan:

- name: The name of the tasks
  module_name: thing1="some-stuff" thing2="some-other-stuff"
  tags: some-tag
- name: The name of the tasks
  module_name: >
    thing1="some-stuff"
    thing2="some-other-stuff"
  tags: some-tag

Penggunaan ">" dan "|" operator harus dibatasi pada modul kondisional dan modul perintah yang mungkin seperti shell atau command yang dimungkinkan.

Konvensi tag dan tag

Tag diberikan berdasarkan relevansi masing-masing item. Level yang lebih tinggi termasuk (misalnya dalam tasks/main.yml) perlu tag tingkat tinggi. Misalnya, *-config or *-install. Tugas yang disertakan dapat memiliki tag yang lebih detail.

Konvensi berikut digunakan:

  • Sebuah tag termasuk kata install menangani tugas-tugas instalasi perangkat lunak. Menjalankan buku pedoman dengan --tags <role> -install hanya menyebarkan perangkat lunak yang diperlukan pada target, dan tidak akan mengkonfigurasinya sesuai kebutuhan Anda atau menjalankan layanan apa pun.

  • Sebuah tag termasuk kata config menyiapkan konfigurasi perangkat lunak (disesuaikan dengan kebutuhan Anda), dan semua komponen yang diperlukan untuk menjalankan layanan yang dikonfigurasi dalam peran. Menjalankan buku pedoman dengan --tags <role> -config hanya dimungkinkan jika target sudah menjalankan tag <role> -install.

  • Tag termasuk kata upgrade menangani semua tugas pemutakhiran.

Konvensi file variabel

File variabel dalam sebuah peran dibagi dalam 3 lokasi:

  1. File defaults/main.yml

  2. File vars/main.yml

  3. File vars/<platform specific> .yml

Variabel dengan prioritas lebih rendah harus dalam defaults/main.yml. Ini memungkinkan pengesampingannya dengan variabel grup atau variabel host. Contoh yang baik untuk ini adalah detail koneksi database default, detail koneksi antrian default, atau mode debug.

Dengan kata lain, defaults/main.yml berisi variabel-variabel yang dimaksudkan untuk dapat ditimpa oleh seorang deployer atau sistem integrasi berkelanjutan. Variabel-variabel ini harus dibatasi sebanyak mungkin, untuk menghindari peningkatan matriks tes.

Vars/main.yml selalu disertakan. Ini berisi variabel generik yang tidak dimaksudkan untuk diubah oleh sebuah deployer. Ini termasuk misalnya informasi statis yang tidak spesifik distribusi (seperti agregasi variabel peran internal misalnya).

Vars/<platform specific> .yml adalah tempat penyimpanan konten spesifik distribusi. Sebagai contoh, file ini akan menyimpan nama paket, url dan kunci repositori, path file, nama layanan / skrip init.

Rahasia

Setiap rahasia (Misalnya: kata sandi) tidak boleh diberikan dengan nilai-nilai standar dalam tugas, peran peran, atau peran standar. Tugas harus diimplementasikan sedemikian rupa sehingga rahasia yang diperlukan, tetapi tidak disediakan, harus mengakibatkan kegagalan pelaksanaan tugas. Penting untuk implementasi yang aman secara default untuk memastikan bahwa lingkungan tidak rentan karena penggunaan produksi dari rahasia default. Pemberi kerja harus dipaksa untuk memberikan nilai variabel rahasia sendiri dengan benar.

Konvensi file tugas

Sebagian besar layanan OpenStack akan mengikuti serangkaian tahapan umum untuk menginstal, mengkonfigurasi, atau memperbarui penyebaran layanan. Ini terlihat ketika Anda meninjau tasks/main.yml untuk peran yang ada.

Jika mengembangkan peran baru, harap ikuti konvensi yang ditetapkan oleh peran yang ada.

Tes konvensi

Kebiasaan menulis tes dijelaskan di halaman Testing

Konvensi OpenStack-Ansible lainnya

Untuk memfasilitasi pengembangan dan pengujian yang diterapkan di semua peran OpenStack-Ansible, sekumpulan folder dan file perlu diimplementasikan. Sepasang skrip konfigurasi dan fasilitasi uji dasar harus mencakup setidaknya yang berikut:

  • tox.ini: Pengujian serat, pembuatan dokumentasi, rilis rilis dan proses eksekusi pembangunan fungsional untuk tes gerbang peran semuanya ditentukan dalam file ini.

  • test-requirements.txt: Persyaratan Python yang harus diinstal ketika menjalankan tes.

  • bindep.txt: Persyaratan biner yang harus diinstal pada host pengujian dijalankan untuk persyaratan Python dan eksekusi toks agar berfungsi. Ini harus disalin dari repositori openstack-ansible-tests dan akan secara otomatis diganti oleh bot proposal kami jika terjadi perubahan.

  • setup.cfg dan setup.py: Informasi tentang repositori yang digunakan saat membuat artefak.

  • run_tests.sh: Script untuk pengembang untuk menjalankan semua tes standar pada host yang sesuai. Ini harus disalin dari repositori openstack-ansible-tests dan akan secara otomatis diganti oleh bot proposal kami jika terjadi perubahan.

  • Vagrantfile: File konfigurasi untuk memungkinkan pengembang membuat mesin virtual pengujian dengan mudah menggunakan Vagrant. Ini harus secara otomatis menjalankan run_tests.sh. Ini harus disalin dari repositori openstack-ansible-tests dan akan secara otomatis diganti oleh bot proposal kami jika terjadi perubahan.

  • README.rst, LICENSE, CONTRIBUTING.rst: Satu set file standar yang isinya cukup jelas.

  • .gitignore: File konfigurasi git standar untuk repositori yang seharusnya cukup seragam di semua repositori. Ini harus disalin dari repositori openstack-ansible-tests dan akan secara otomatis diganti oleh bot proposal kami jika terjadi perubahan.

  • .gitreview: File standar yang dikonfigurasi untuk proyek untuk menginformasikan kepada plugin git-review di mana menemukan remote gerrit hulu untuk repositori.

  • Folder docs/ dan releasenotes/ perlu ada dan dikonfigurasikan dengan benar.

Silakan lihat peran seperti os_cinder, os_keystone, atau os_neutron untuk file terbaru.

Kemandirian teknologi Container

Implementasi peran harus dilakukan sedemikian rupa sehingga agnostik sehubungan dengan apakah itu diimplementasikan dalam container, atau pada host fisik. Infrastruktur pengujian dapat menggunakan container untuk pemisahan layanan, tetapi jika peran digunakan oleh buku pedoman yang menargetkan host, ia harus berfungsi terlepas dari apakah host itu adalah container, server virtual, atau server fisik. Penggunaan container untuk uji peran tidak diperlukan tetapi mungkin berguna untuk mensimulasikan multi-node yang dibangun sebagai bagian dari infrastruktur pengujian.

Distribusi minimum yang didukung

Lihat halaman kami Distribusi yang didukung.