Nhảy tới nội dung

Giúp xây dựng Flarum

Bạn quan tâm đến việc đóng góp vào sự phát triển của Flarum? Thật tuyệt! Từ mở báo cáo lỗi để tạo ra một yêu cầu kéo: mỗi một yêu cầu đều được đánh giá cao và chào đón. Flarum sẽ không thể thực hiện được nếu không có sự đóng góp của cộng đồng.

Trước khi đóng góp, vui lòng đọc quy tắc ứng xử.

Tài liệu này là hướng dẫn cho các nhà phát triển muốn đóng góp mã cho Flarum. Nếu bạn chỉ mới bắt đầu, chúng tôi khuyên bạn nên đọc tài liệu Bắt đầu trong tài liệu Tiện ích mở rộng để hiểu thêm một chút về cách hoạt động của Flarum.

Tại sao lại đóng góp Flarum?#

Có tác động thực sự. Có hàng nghìn phiên bản Flarum, với hàng triệu người dùng cuối tổng hợp. Bằng cách đóng góp cho Flarum, mã của bạn sẽ có tác động tích cực đến tất cả chúng.

🔮 Định hình tương lai của Flarum. Chúng tôi có một công việc tồn đọng lâu dài và thời gian có hạn. Nếu bạn sẵn sàng ủng hộ một tính năng hoặc thay đổi, thì điều đó có nhiều khả năng xảy ra hơn và bạn sẽ có thể đưa ra tầm nhìn của mình cho nó. Ngoài ra, lộ trình và các cột mốc quan trọng của chúng tôi được thiết lập bởi nhóm phát triển cốt lõi của chúng tôi, và tất cả chúng tôi đều bắt đầu với tư cách là những người đóng góp. Con đường tốt nhất để tạo ảnh hưởng là đóng góp.

🧑‍💻 Trở thành một kỹ sư giỏi hơn. codebase của chúng tôi hiện đại và chúng tôi đánh giá cao kỹ thuật tốt và mã sạch. Ngoài ra còn có rất nhiều vấn đề thú vị, đầy thách thức cần giải quyết liên quan đến thiết kế, cơ sở hạ tầng, hiệu suất và khả năng mở rộng. Đặc biệt nếu bạn là sinh viên hoặc mới bắt đầu sự nghiệp, làm việc trên Flarum là một cơ hội tuyệt vời để xây dựng các kỹ năng phát triển.

🎠 Thật thú vị! Chúng tôi thực sự thích làm việc trên Flarum: có rất nhiều thử thách thú vị và các tính năng thú vị để xây dựng. Chúng tôi cũng có một cộng đồng tích cực trên diễn đàn của chúng tôimáy chủ Discord.

Những gì cần làm#

Kiểm tra Các cột mốc sắp tới của chúng tôi để có cái nhìn tổng quan về những việc cần phải làm. Xem nhãn Issue đầu tiên cho danh sách các vấn đề tương đối dễ bắt đầu. Nếu có bất cứ điều gì bạn không chắc chắn, đừng ngần ngại hỏi! Tất cả chúng tôi chỉ mới bắt đầu một lần.

Nếu bạn đang lên kế hoạch tiếp tục làm việc gì đó, vui lòng nhận xét về vấn đề có liên quan hoặc tạo một vấn đề mới trước. Bằng cách này, chúng tôi có thể đảm bảo rằng công việc quý giá của bạn không trở nên vô ích.

Vì Flarum rất hướng đến tiện ích mở rộng, chúng tôi thực sự khuyên bạn nên tài liệu về tiện ích mở rộng của chúng tôi như một tài liệu tham khảo khi làm việc trên lõi, cũng như cho các tiện ích mở rộng đi kèm. Bạn nên bắt đầu với phần giới thiệu để hiểu rõ hơn về triết lý mở rộng của chúng tôi.

Thiết lập môi trường#

Thiết lập Codebase cục bộ#

flarum/flarum là một ứng dụng "khung" sử dụng Composer để tải xuống flarum/corenhiều tiện ích mở rộng. Để giải quyết những vấn đề này, chúng tôi khuyên bạn nên tạo và sao chép chúng vào Kho lưu trữ đường dẫn của Composer:

git clone https://github.com/flarum/flarum.gitcd flarum
# Thiết lập kho lưu trữ đường dẫn Composer cho các gói Flarumcomposer config repositories.0 path "packages/*"git clone https://github.com/<username>/core.git packages/coregit clone https://github.com/<username>/tags.git packages/tags # etc

Tiếp theo, hãy đảm bảo rằng Composer chấp nhận các bản phát hành không ổn định từ các bản sao cục bộ của bạn bằng cách đặt khóa minimum-stability thành dev trong composer.json.

Cuối cùng, chạy composer install để hoàn tất cài đặt từ kho đường dẫn.

Sau khi cài đặt cục bộ của bạn được thiết lập, hãy đảm bảo rằng bạn đã bật chế độ debug trong config.php và đặt display_errors thành On trong cấu hình php của bạn. Điều này sẽ cho phép bạn xem chi tiết lỗi cho cả Flarum và PHP. Chế độ gỡ lỗi cũng buộc phải biên dịch lại các tệp nội dung của Flarum theo từng yêu cầu, loại bỏ nhu cầu gọi php flarum cache: clear sau mỗi lần thay đổi đối với javascript hoặc CSS của tiện ích mở rộng.

Mã front-end của Flarum được viết bằng ES6 và được chuyển sang JavaScript. Trong quá trình phát triển, bạn sẽ cần phải biên dịch lại JavaScript bằng cách sử dụng Node.js. Vui lòng không commit kết quả các tệp trong dist khi gửi PRs; điều này sẽ tự động được xử lý khi các thay đổi được hợp nhất vào branch master.

cd packages/core/jsnpm installnpm run dev

Quá trình này cũng giống như các tiện ích mở rộng.

cd packages/tags/jsnpm installnpm link ../../core/jsnpm run dev

Công cụ phát triển#

Sau khi bạn đã tách và nhân bản các kho lưu trữ mà bạn sẽ làm việc, bạn sẽ cần thiết lập lưu trữ cục bộ để có thể kiểm tra các thay đổi của mình. Flarum hiện không đi kèm với máy chủ phát triển, vì vậy bạn sẽ cần thiết lập Apache/NGINX/Caddy/vv để cài đặt máy chủ Flarum cục bộ này.

Ngoài ra, bạn có thể sử dụng các công cụ như, Laravel Valet (Mac), XAMPP (Windows), hoặc Docker-Flarum (Linux) để máy chủ diễn đàn cục bộ.

Hầu hết các cộng tác viên của Flarum đều phát triển với PHPStorm hoặc Visual Studio Code.

Quy trình phát triển#

Quy trình đóng góp điển hình trông giống như sau:

  1. 🧭 Lập kế hoạch đóng góp của bạn

  2. 🌳 Branch tách branch thích hợp thành một branch tính năng mới.

    • Bug fixes nên được gửi đến branch ổn định mới nhất.
    • Minor các tính năng hoàn toàn tương thích ngược với bản phát hành Flarum hiện tại có thể được gửi đến nhánh ổn định mới nhất.
    • Major các tính năng phải luôn được gửi tới nhánh master, nhánh chứa bản phát hành Flarum sắp tới.
    • Nội bộ chúng tôi sử dụng lược đồ đặt tên <initials>/<short-description> (ví dụ: tz/refactor-frontend).
  3. 🔨 Viết code.

  4. 🚦 Thử nghiệm code của bạn.

    • Thêm các bài kiểm tra đơn vị khi cần thiết khi sửa lỗi hoặc thêm tính năng.
    • Chạy bộ thử nghiệm với vendor/bin/phpunit trong thư mục gói có liên quan.
    • Xem ở đây để biết thêm thông tin về thử nghiệm trong Flarum.
  5. 💾 Commit code của bạn với một thông điệp mô tả.

    • Nếu thay đổi của bạn giải quyết được sự cố hiện có (thông thường, nó phải) bao gồm "Bản sửa lỗi số 123" trên một dòng mới, trong đó 123 là số sự cố.
    • Viết một thông điệp commit tốt.
  6. 🎁 Gửi một Pull Request trên GitHub.

    • Điền vào mẫu pull request.
    • Nếu thay đổi của bạn là trực quan, hãy bao gồm ảnh chụp màn hình hoặc GIF thể hiện thay đổi.
    • KHÔNG đăng ký các tệp dist JavaScript. Chúng sẽ được biên dịch tự động khi hợp nhất.
  7. 🤝 Đính hôn với nhóm Flarum để được chấp thuận.

    • Các thành viên trong nhóm sẽ xem xét mã của bạn. Chúng tôi có thể đề xuất một số thay đổi hoặc cải tiến hoặc lựa chọn thay thế, nhưng đối với những thay đổi nhỏ, yêu cầu kéo của bạn sẽ được chấp nhận nhanh chóng.
    • Khi giải quyết phản hồi, hãy đẩy các commit bổ sung thay vì ghi đè hoặc cắt bỏ (chúng tôi sẽ xóa khi hợp nhất).
  8. 🕺 Nhảy giống như bạn vừa đóng góp cho Flarum.

Kiểu coding#

Để giữ cho codebase Flarum sạch sẽ và nhất quán, chúng tôi có một số nguyên tắc về kiểu coding mà chúng tôi tuân theo. Khi nghi ngờ, hãy đọc mã nguồn.

Đừng lo lắng nếu kiểu mã của bạn không hoàn hảo! StyleCI và Prettier sẽ tự động kiểm tra định dạng cho mọi yêu cầu kéo. Điều này cho phép chúng tôi tập trung vào nội dung của đóng góp, không phải kiểu coding.

PHP#

Flarum tuân theo tiêu chuẩn mã hóa PSR-2 và tiêu chuẩn autoloading PSR-4. Trên hết, chúng tôi tuân thủ một số quy tắc phong cách khác. Chúng tôi sử dụng gợi ý kiểu PHP 7 và khai báo kiểu trả về nếu có thể và PHPDoc để cung cấp tài liệu nội tuyến. Hãy thử và bắt chước kiểu được sử dụng bởi phần còn lại của codebase trong các đóng góp của bạn.

  • Namespaces phải là số ít (ví dụ: Flarum\Discussion, không phải Flarum\Discussions)
  • Interfaces phải được gắn với Interface (ví dụ: MailableInterface)
  • Class Abstract phải được bắt đầu bằng Abstract (ví dụ: AbstractModel)
  • Traits phải được gắn với Trait (ví dụ: ScopeVisibilityTrait)

JavaScript#

JavaScript của Flarum chủ yếu tuân theo Hướng dẫn kiểu Airbnb. Chúng tôi sử dụng ESDoc để cung cấp tài liệu nội tuyến.

Cơ sở dữ liệu#

Cột nên được đặt tên theo kiểu dữ liệu:

  • DATETIME hoặc TIMESTAMP: {verbed}_at (ví dụ: created_at, read_at) hoặc {verbed}_until (ví dụ: suspended_until)
  • INT là một số: {noun}_count (ví dụ: comment_count, word_count)
  • Khoá ngoại: {verbed}_{entity}_id (ví dụ: hidden_user_id)
    • Có thể bỏ qua động từ cho quan hệ chính (ví dụ: người đăng bài viết là user_id)
  • BOOL: is_{adjective} (ví dụ: is_locked)

Bảng nên được đặt tên như sau:

  • Sử dụng dạng số nhiều (discussions)
  • Phân tách nhiều từ bằng dấu gạch dưới (access_tokens)
  • Đối với bảng mối quan hệ, hãy nối hai tên bảng ở dạng số ít với dấu gạch dưới theo thứ tự bảng chữ cái (ví dụ: discussion_user)

CSS#

Các class CSS của Flarum gần như tuân theo các quy ước đặt tên CSS SUIT bằng cách sử dụng định dạng .ComponentName-descendentName--modifierName.

Bản dịch#

Chúng tôi sử dụng định dạng khóa tiêu chuẩn để đặt tên các khóa dịch một cách mô tả và nhất quán.

Thỏa thuận cấp phép cộng tác viên#

Bằng cách đóng góp mã của bạn cho Flarum, bạn cấp cho Flarum Foundation (Stichting Flarum) một giấy phép không độc quyền, không thể thu hồi, trên toàn thế giới, miễn phí bản quyền, có thể cấp phép lại, có thể chuyển nhượng theo tất cả các quyền sở hữu trí tuệ liên quan của bạn (bao gồm bản quyền, bằng sáng chế và bất kỳ quyền nào khác ), để sử dụng, sao chép, chuẩn bị các sản phẩm phái sinh, phân phối và trình diễn công khai và hiển thị các Đóng góp theo bất kỳ điều khoản cấp phép nào, bao gồm nhưng không giới hạn: (a) giấy phép nguồn mở như giấy phép MIT; và (b) giấy phép nhị phân, độc quyền hoặc thương mại. Ngoại trừ các giấy phép được cấp ở đây, Bạn bảo lưu mọi quyền, quyền sở hữu và lợi ích đối với và đối với Khoản đóng góp.

Bạn xác nhận rằng bạn có thể cấp cho chúng tôi các quyền này. Bạn tuyên bố rằng Bạn có quyền hợp pháp để cấp giấy phép trên. Nếu chủ lao động của Bạn có quyền đối với tài sản trí tuệ mà Bạn tạo ra, Bạn tuyên bố rằng Bạn đã nhận được sự cho phép để thực hiện các Đóng góp thay mặt cho chủ lao động đó, hoặc chủ lao động của Bạn đã từ bỏ các quyền đó đối với các Đóng góp đó.

Bạn tuyên bố rằng Đóng góp là tác phẩm gốc của bạn về quyền tác giả và theo hiểu biết của Bạn, không có người khác yêu cầu hoặc có quyền yêu cầu, bất kỳ quyền nào trong bất kỳ phát minh hoặc bằng sáng chế nào liên quan đến Đóng góp. Bạn cũng tuyên bố rằng Bạn không bị ràng buộc về mặt pháp lý, cho dù bằng cách ký kết thỏa thuận hay bằng cách khác, theo bất kỳ cách nào xung đột với các điều khoản của giấy phép này.

Flarum Foundation thừa nhận rằng, ngoại trừ được mô tả rõ ràng trong Thỏa thuận này, bất kỳ Khoản đóng góp nào mà bạn cung cấp đều dựa trên CƠ SỞ "NGUYÊN TRẠNG", KHÔNG CÓ BẢO ĐẢM HOẶC ĐIỀU KIỆN BẤT KỲ HÌNH THỨC NÀO, RÕ RÀNG HOẶC NGỤ Ý, BAO GỒM, KHÔNG GIỚI HẠN, BẤT KỲ BẢO ĐẢM HOẶC ĐIỀU KIỆN NÀO CÓ TIÊU ĐỀ, KHÔNG VI PHẠM, KHẢ NĂNG DI ĐỘNG HOẶC PHÙ HỢP VỚI MỤC ĐÍCH CỤ THỂ.