Web Development

Revision History

Date	Version	Authors	Description
2020-08-04	1.0	Adli I. Ifkar	Initial Version
2021-01-22	1.1	Adli I. Ifkar	Updated Tools
2021-05-03	2.0	Adli I. Ifkar	Removing Windows, Added ERD, and updated Issues

1. Overview

Tim IT Yayasan Vitka adalah tim yang bertanggung jawab terhadap pengembangan software di lingkungan Politeknik Pariwisata Batam, Institut Teknologi Batam, dan Yayasan Vitka. Software yang dikembangkan saat ini difokuskan pada kebutuhan akademik dan penunjang kegiatan akademik lainnya. Teknologi yang digunakan berbasis web. Software yang ditulis dengan baik dan rapi memiliki banyak kelebihan. Software tersebut akan memiliki bug lebih sedikit dan akan berjalan lebih efisien dibandingkan dengan software yang tidak ditulis dengan baik. Karena software memiliki life cycle dan Sebagian besar dari life cycle tersebut adalah maintenance, tim pengembang maupun anggota tim yang akan datang akan lebih mudah untuk melakukan maintenance dan merubah program sesuai dengan kebutuhan. Tim IT Yayasan Vitka membuat standarisasi dan panduan singkat untuk memastikan seluruh anggota tim IT yang terlibat memiliki visi yang sama dalam mengembangkan software. Standar dan panduan ini tidaklah konstan, namun dapat berevolusi sesuai dengan kebutuhan dan kesepakatan ke depannya.

2. Standard Tools

2.1 Tools & IDE

Fokus pengembangan pada Yayasan Vitka adalah web application berbasis Laravel dan Backpack for Laravel. Tools utama yang dibutuhkan adalah:
a. PHP >= 8.0
b. PHP >= 7.4.14
c. Git >= 2.27.0
d. MySQL >= 8.0.17
e. Redis >= 6.0
Adapun untuk GUI Tools & IDE yang digunakan adalah:
a. PHPStorm
b. SmartGit untuk git
c. HeidiSQL / MySQL Workbench
d. Insomnia / PostMan untuk API Testing
e. Google Chrome

2.2 Linux

Linux yang disarankan adalah Ubuntu 20.04 / POP! OS 20.04. Developer dapat memanfaatkan Laravel Homestead atau Docker Stack, atau menggunakan package dari repository.

2.3 MacOS

Developer dapat memanfaatkan Laravel Homestead atau Laravel Homestead, atau menggunakan package Homebrew.

3. Coding Standard

Coding Standard adalah tata cara developer dalam menulis kode. Dalam hal ini, beberapa standar yang harus dipenuhi dapat dilihat pada point 3.1

3.1 Penulisan kode PHP

Penulisan kode PHP harus sesuai dengan standar PSR-2 dan PSR-4. Selain itu, developer diwajibkan mengikuti naming convention yang telah disepakati, yaitu:
a. Controller
Controller menggunakan bentuk tunggal (singular) dalam Bahasa Inggris, tanpa underscore dan spasi, dan menggunakan CamelCase.
Contoh: ArticleController, DocumentController, StudentRegisterController.
b. Database Table
Tabel pada database menggunakan snake_case, lowercase, menggunakan bentuk jamak (plural) dalam Bahasa Inggris.
Contoh: students, documents, student_registers.
c. Database Pivot Table
Pivot Tabel pada database menggunakan snake_case, lowercase, menggunakan bentuk tunggal (singular) dalam Bahasa Inggris.Nama tabel diurutkan sesuai abjad mengikuti tabel referensi nya.
Contoh: Pivot Table antara classes dan student_registers adalah class_studentregister.
d. Table Column
Kolom pada tabel menggunakan lowercase, dan snake_case. Kolom primary key yang menggunakan auto_increment adalah id.
Contoh: username, email.
e. Table Column (Foreign Key)
Jika tabel memiliki referensi dengan tabel lain (foreign key), maka nama kolom adalah nama tabel yang direferensikan dalam bentuk singular ditambah ‘_’ dan nama kolomnya.
Sebagai contoh, tabel cities memiliki relasi dengan tabel provinces, dimana satu provinces memiliki banyak cities. Jika primary key pada tabel provinces adalah id, maka kolom referensi pada tabel cities adalah province_id. Jika primary key pada tabel provinces adalah uuid, maka kolom referensi pada tabel cities adalah province_uuid.
f. Model
Model menggunakan bentuk tunggal (singular), tidak menggunakan underscore, dan menggunakan CamelCase. Contoh: StudentRegister.
g. Model Properties
Model Properties menggunakan standar yang sama dengan Table Column. h. Model Method
Menggunakan CamelCase dengan huruf pertama lowercase. Penamaan method disesuaikan dengan value return nya. Jika return value memiliki isi lebih dari satu data (array atau collection), maka penamaan method menggunakan bentuk plural. Sedangkan jika return value hanya memiliki satu nilai atau satu record (contoh: relasi antara city belongs to province), maka penamaan method menggunakan bentuk plural. Contoh: $model->billings(), $model->billingPayments(), $model->cities(), $model->provice().
i. File Blade
File blade menggunakan snake_case.
Contoh: student_detail.blade.php
j. Translation
Untuk tampilan yang berhubungan dengan user, diwajibkan mempersiapkan file translasi untuk Bahasa Indonesia dan Bahasa Inggris.

3.2 HTML CSS JS

Indentasi pada blok kode menggunakan 4 spasi. Standar penulisan kode program pada JavaScript disesuaikan dengan PHP agar seragam.

3.3 Development Focus

Pengembangan aplikasi web oleh Tim IT Yayasan Vitka harus fungsional, mengikuti best practice baik untuk frontend (UI dan styling) maupun backend (performance dan reliability). Selain itu, dikarenakan lebih dari 60% pengguna saat ini mengakses halaman web menggunakan smartphone, maka developer harus menitik beratkan fungsionalitas pada smartphone terutama pada halaman yang berhubungan dengan pengguna.

3.4 ERD

Entity Relationship Diagram, atau ERD, adalah desain dari suatu database dan relasinya. Sebelum memulai pengembangan aplikasi dan atau modul, ERD harus dipersiapkan terlebih dahulu, dan didokumentasikan ke platform yang telah disetujui oleh IT Manager Yayasan Vitka.

4. Documentation Standard

Dokumentasi internal bertujuan untuk meningkatkan readability dari sebuah software. Standar dokumentasi untuk PHP dapat dilihat pada https://github.com/php-fig/fig- standards/blob/master/proposed/phpdoc.md. Untuk bahasa program lainnya, pada dasarnya, setiap function, class, dan atau trait harus memiliki DocBlock yang menjelaskan fungsi dari function / class / trait tersebut.

5. Repository Access & Usage

Repositori, dalam konteks ini mengacu pada Repositori Git milik Yayasan Vitka adalah sentral penyimpanan source code yang juga berfungsi sebagai pencatat perubahan dan alat bantu untuk berkolaborasi, terutama di lingkungan Software Development di Yayasan Vitka. Repositori milik Yayasan Vitka terletak di Github dengan alamat https://github.com/yayasanvitka.

5.1 Hak Akses

Akses kepada repositori diberikan kepada developer yang terlibat di dalam pengembangan software pada Yayasan Vitka dan atau pihak lainnya yang diberikan akses sesuai pertimbangan. Setiap anggota tim tidak boleh melakukan forking tanpa seizin IT Manager Yayasan Vitka, dan dilarang untuk menunjukkan source code dengan alasan apapun kepada pihak luar kecuali dengan pertimbangan tertentu dan seizin dari IT Manager Yayasan Vitka. Jika developer tidak lagi menjadi anggota tim pengembangan software, maka hak akses kepada repository Yayasan Vitka akan dicabut.

5.2 Branching

Setiap anggota tim pengembangan software dipersilahkan membuat branch pada repository untuk memisahkan working directory antar anggota tim. Branching sangat disarankan untuk menghindari conflict, terutama jika lebih dari satu anggota tim mengerjakan modul yang sama diwaktu yang bersamaan.

5.3 Commit & Push

Commit dilakukan untuk menyimpan perubahan pada repository. Sedangkan push adalah menyimpan commit yang telah dilakukan pada source repository di Github. Setiap commit yang dilakukan harus berupa incremental changes, atau perubahan yang bersifat tahap demi tahap, dan harus memiliki commit message yang jelas dan rinci. Anggota tim tidak diperkenankan untuk melakukan commit secara langsung ke branch master dan release/latest.

5.4 Pull Request & Merging to Master

Pull request bertujuan untuk menggabungkan branch yang sedang dikembangkan dengan branch master. Pull request dilakukan pada branch yang sudah selesai dikembangkan dan sudah melewati test. Pull request harus direview oleh IT Manager terlebih dahulu sebelum di accept.

5.5 Release

Software yang telah melewati test dapat dirilis untuk pengguna. Setiap rilis harus memiliki Changelog detail, dan harus memiliki versi unik. Penomoran versi aplikasi dilakukan oleh Head Development Team dengan mengikuti standar semantic versioning. Rilis ke server dilakukan oleh PIC yang telah ditunjuk.

6. Issue & Tracking

Setiap software yang dikembangkan tidak lepas dari adanya bugs atau issue. Untuk memudahkan melakukan tracking terhadap issue, Tim IT Yayasan Vitka dapat menggunakan fitur issue pada GitHub untuk melaporkan issue yang ditemukan. Adapun guidelines untuk pembuatan issue adalah:
a. Gunakan tag yang sesuai untuk issue yang ada, seperti [Bug] untuk bug yang ditemukan pada program, atau [Feature Request] untuk permintaan penambahan fitur.
b. Issue harus memiliki data siapa yang menemukan / melakukan request, narasi dari issue, dan ekspektasi dari program.
c. Issue, Feature Request, dan hal – hal lain yang berhubungan dengan pengembangan software harus didokumentasikan di GitHub sesuai dengan repository yang bersangkutan atau pada project di organizational level. d. Komunikasi untuk issue, feature request, dan hal – hal lain yang berhubungan dengan pengembangan software harus dilakukan melalui repository software yang bersangkutan atau pada project di organizational level.

6.1 Eskalasi Issue

Jika issue tidak dapat diselesaikan oleh anggota tim yang bersangkutan, misalnya dikarenakan SOP di lapangan yang tidak sesuai dengan ekspektasi program, anggota tim dapat menghubungi head development melalui GitHub mention pada issue, Microsoft Teams, atau Email untuk di ditindak lanjuti. Eskalasi issue juga dapat dilakukan jika issue tersebut sifatnya urgent dan membutuhkan perubahan langsung pada database.

6.2 Penyelesaian

Issue yang telah diselesaikan harus ditutup, dan melakukan referencing pada commit yang menyelesaikan issue tersebut pada GitHub. Pull request dapat dilakukan untuk menggabungkan commit tersebut pada master branch di repository.