Berkontribusi pada GSPAY Go SDK

Terima kasih atas minat Anda untuk berkontribusi pada GSPAY Go SDK! Dokumen ini menyediakan panduan dan informasi untuk kontributor.

🚀 Cara Berkontribusi

🐛 Laporan Bug: Laporkan bug melalui GitHub Issues
💡 Permintaan Fitur: Sarankan fitur baru atau perbaikan
📝 Dokumentasi: Tingkatkan dokumentasi, contoh, atau panduan
💻 Kontribusi Kode: Kirim pull request untuk fitur baru atau perbaikan bug
🧪 Pengujian: Tambahkan test atau tingkatkan cakupan test

📋 Setup Development

Prasyarat

Go 1.25.6 atau lebih baru
Git
Pemahaman dasar tentang Go modules dan testing

Langkah-langkah Setup

Fork repository di GitHub

Clone fork Anda:

git clone https://github.com/USERNAME_ANDA/gspay-go-sdk.git
cd gspay-go-sdk

Install dependencies:
```
go mod download
```
Jalankan tests untuk memastikan semuanya berfungsi:
```
go test ./...
```
Buat feature branch:
```
git checkout -b feature/nama-fitur-anda
```

🏗️ Struktur Proyek

gspay-go-sdk/
├── src/
│   ├── balance/     # Layanan query saldo
│   ├── client/      # HTTP client dan fungsionalitas inti
│   │   └── logger/  # Structured logging (interface Handler, Std, Nop)
│   ├── constants/   # Kode bank, status pembayaran, channel
│   ├── errors/      # Tipe error dan penanganan
│   ├── helper/      # Utilitas helper
│   │   ├── amount/  # Utilitas pemformatan jumlah
│   │   └── gc/      # Manajemen buffer pool
│   ├── i18n/        # Internasionalisasi (bahasa, terjemahan)
│   ├── internal/    # Utilitas internal (tanda tangan, sanitasi)
│   ├── payment/     # Layanan pembayaran (IDR, THB/MYR mendatang)
│   └── payout/      # Layanan pencairan (IDR)
├── examples/        # Contoh penggunaan
├── go.mod           # Definisi Go module
└── README.md        # Dokumentasi utama

💻 Standar Kode

Gaya Kode Go

Ikuti format Go standar: go fmt
Gunakan gofmt -s untuk penyederhanaan tambahan
Jalankan go vet dan perbaiki semua peringatan
Pastikan golint lolos (jika tersedia)

Konvensi Penamaan

// Tipe
type PaymentRequest struct { ... }    // PascalCase untuk tipe yang diekspor
type paymentAPIRequest struct { ... } // camelCase untuk tipe internal

// Fungsi
func CreatePayment(...) (...)         // PascalCase untuk fungsi yang diekspor
func createAPIRequest(...) (...)      // camelCase untuk fungsi internal

// Variabel
var PaymentStatusPending = 0          // PascalCase untuk konstanta yang diekspor
var defaultTimeout = 30 * time.Second // camelCase untuk variabel internal

Penanganan Error

Kembalikan error bertipe dari paket errors
Gunakan errors.New untuk mengembalikan error sentinel dengan konteks dan lokalisasi
errors.New secara otomatis membungkus penyebab dengan %w, mendukung standar errors.Is/errors.As
Sertakan konteks dalam pesan error

Dokumentasi

Tambahkan komentar doc untuk semua fungsi, tipe, dan method yang diekspor
Gunakan format Go doc yang benar
Sertakan contoh penggunaan jika membantu

Internasionalisasi (i18n)

SDK mendukung pesan error dan pesan log yang terlokalisasi. Saat menambahkan pesan yang menghadap pengguna:

Menambahkan Pesan Error

Tambahkan message key di src/i18n/messages.go:

const (
    MsgNewErrorKey MessageKey = "new_error_key"
)

Tambahkan terjemahan untuk semua bahasa yang didukung:

var translations = map[Language]map[MessageKey]string{
    English: {
        MsgNewErrorKey: "English error message",
    },
    Indonesian: {
        MsgNewErrorKey: "Pesan error dalam Bahasa Indonesia",
    },
}

Gunakan pesan terlokalisasi dalam validation errors:

return errors.NewValidationError("field", 
    errors.GetMessage(s.client.Language, errors.KeyNewError))

Re-export di paket errors untuk kemudahan:

// src/errors/errors.go
const KeyNewError = i18n.MsgNewErrorKey

Menambahkan Pesan Log

Tambahkan log message key di src/i18n/messages.go:

const (
    LogNewOperation MessageKey = "log_new_operation"
)

Tambahkan terjemahan untuk semua bahasa yang didukung:

var translations = map[Language]map[MessageKey]string{
    English: {
        LogNewOperation: "performing new operation",
    },
    Indonesian: {
        LogNewOperation: "melakukan operasi baru",
    },
}

Gunakan helper I18n dari client dalam kode service:

// Dalam method service, gunakan s.client.I18n() untuk pesan log
s.client.Logger().Info(s.client.I18n(i18n.LogNewOperation),
    "key", "value",
)

// Dalam method client, gunakan c.I18n() langsung
c.logger.Debug(c.I18n(i18n.LogSendingRequest),
    "endpoint", c.LogEndpoint(endpoint),
)

Konvensi Penamaan Message Key

Pesan error: Awali dengan Msg (misal: MsgInvalidAmount, MsgRequestFailed)
Pesan log: Awali dengan Log (misal: LogCreatingIDRPayment, LogRequestCompleted)

Logging

Saat menambahkan logging ke komponen SDK:

Gunakan paket logger di src/client/logger:

import "github.com/H0llyW00dzZ/gspay-go-sdk/src/client/logger"

// Level log
logger.LevelDebug  // Debugging detail
logger.LevelInfo   // Pesan operasional umum
logger.LevelWarn   // Kondisi peringatan
logger.LevelError  // Kondisi error

Implementasikan interface Handler untuk logger kustom:

type Handler interface {
    Log(level Level, msg string, args ...any)
}

Sanitasi endpoint saat logging URL yang mengandung auth key:

import "github.com/H0llyW00dzZ/gspay-go-sdk/src/internal/sanitize"

safeEndpoint := sanitize.Endpoint(endpoint)
// Meredaksi auth key sebagai [REDACTED]

Pengecualian: Mode WithDebug(true) menampilkan endpoint mentah untuk debugging

Memodifikasi Endpoint API

Edit src/constants/endpoints.go untuk menambah atau memodifikasi EndpointKey dan path dalam map endpoints.
Update implementasi layanan untuk menggunakan constants.GetEndpoint() alih-alih string hardcoded.
Update pembuatan tanda tangan jika parameter berubah.
Update struct request/response.
Update tests untuk memverifikasi perubahan dan memastikan coverage untuk endpoint baru.

🧪 Pengujian

Persyaratan Test

100% coverage untuk kode baru
Gunakan table-driven tests untuk berbagai skenario
Mock respons HTTP menggunakan httptest
Test kasus sukses dan error
Test edge cases dan validasi input

Struktur Test

func TestPaymentService_Create(t *testing.T) {
    t.Run("pembuatan pembayaran berhasil", func(t *testing.T) {
        // Setup mock server
        server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // Mock respons API
            w.Header().Set("Content-Type", "application/json")
            json.NewEncoder(w).Encode(map[string]any{
                "code": 200,
                "data": `{"payment_url":"https://...","id":"123"}`,
            })
        }))
        defer server.Close()

        // Test kode Anda
        client := New("auth", "secret", WithBaseURL(server.URL))
        svc := payment.NewIDRService(client)

        resp, err := svc.Create(context.Background(), &payment.IDRRequest{
            TransactionID: "TXN123",
            Username:      "user123",
            Amount:        50000,
        })

        assert.NoError(t, err)
        assert.NotEmpty(t, resp.PaymentURL)
    })
}

Menjalankan Tests

# Jalankan semua tests
go test ./...

# Jalankan dengan coverage
go test ./... -cover

# Jalankan paket tertentu
go test ./src/payment

# Jalankan dengan output verbose
go test ./... -v

🔧 Menambahkan Metode Pembayaran Baru

Untuk Mata Uang Baru (contoh: THB, MYR)

Tambahkan konstanta di src/constants/:

// Kode mata uang
const CurrencyTHB Currency = "THB"

// Kode bank
var BanksTHB = map[string]string{
    "BBL": "Bangkok Bank",
    // ... tambahkan bank lainnya
}

// Channel pembayaran
var ChannelsTHB = []string{"QRIS", "BANK_TRANSFER"}

Buat layanan pembayaran di src/payment/:

// src/payment/thb.go
type THBService struct { client *client.Client }

func NewTHBService(c *client.Client) *THBService {
    return &THBService{client: c}
}

func (s *THBService) Create(ctx context.Context, req *THBRequest) (*THBResponse, error) {
    // Implementasi mengikuti pola layanan IDR
}

Tambahkan verifikasi callback:

func (s *THBService) VerifyCallback(callback *THBCallback) error {
    // Verifikasi tanda tangan MD5
}

Update client untuk mendukung layanan baru:

// Tambahkan konstruktor layanan THB
func NewTHBService(c *Client) *THBService { ... }

Tambahkan tests komprehensif mengikuti pola yang ada
Update dokumentasi di README.md dan examples

Checklist Implementasi

Konstanta ditambahkan untuk mata uang, bank, channel
Layanan pembayaran diimplementasikan dengan penanganan error yang tepat
Verifikasi callback diimplementasikan
Unit tests dengan 100% coverage
Integration tests dengan mock API
Dokumentasi diupdate
Contoh ditambahkan
Changelog diupdate

📝 Proses Pull Request

Buat feature branch dari main:
```
git checkout -b feature/add-thb-support
```
Buat perubahan Anda mengikuti standar kode
Jalankan tests dan pastikan lolos:
```
go test ./... -v
go vet ./...
```
Update dokumentasi jika diperlukan

Commit perubahan Anda dengan pesan yang jelas:

git add .
git commit -m "feat: tambah dukungan pembayaran THB

- Implementasi layanan pembayaran THB
- Tambah verifikasi callback
- Tambah tests komprehensif

Closes #123"

Push ke fork Anda:
```
git push origin feature/add-thb-support
```
Buat Pull Request di GitHub:
- Gunakan judul dan deskripsi yang jelas
- Referensikan issue terkait
- Sertakan screenshot/demo untuk perubahan UI
- Minta review dari maintainer

Format Judul PR

type(scope): deskripsi

Types: feat, fix, docs, style, refactor, test, chore
Contoh:
- feat(thb): tambah dukungan pembayaran THB
- fix(callback): perbaiki bug verifikasi tanda tangan
- docs(readme): update instruksi instalasi

🐛 Laporan Bug

Saat melaporkan bug, harap sertakan:

Versi Go: go version
Versi SDK: Hash commit Git atau tag
Perilaku yang diharapkan
Perilaku aktual
Langkah-langkah untuk mereproduksi
Pesan error/log
Contoh kode yang mendemonstrasikan masalah

💡 Permintaan Fitur

Permintaan fitur harus mencakup:

Kasus penggunaan: Masalah apa yang diselesaikan?
Solusi yang diusulkan: Bagaimana seharusnya bekerja?
Alternatif yang dipertimbangkan: Pendekatan lain?
Konteks tambahan: Screenshot, contoh, dll.

📜 Kode Etik

Proyek ini mengikuti kode etik untuk memastikan lingkungan yang ramah bagi semua kontributor:

Bersikap hormat dan inklusif
Fokus pada umpan balik yang konstruktif
Terima tanggung jawab atas kesalahan
Tunjukkan empati terhadap kontributor lain
Bantu menciptakan komunitas yang positif

📞 Mendapatkan Bantuan

Dokumentasi: Periksa README.md dan examples terlebih dahulu
Issues: Cari issue yang ada sebelum membuat yang baru
Discussions: Gunakan GitHub Discussions untuk pertanyaan
Komunitas: Bergabung dengan komunitas Go yang relevan untuk pertanyaan umum

🎉 Penghargaan

Kontributor akan diakui:

Di CHANGELOG untuk kontribusi signifikan
Sebagai co-author pada rilis
Di daftar kontributor proyek
Melalui insight kontributor GitHub

Terima kasih telah berkontribusi pada GSPAY Go SDK! 🚀

FilesExpand file tree

CONTRIBUTING.id.md

Latest commit

History