Trang này được dịch bởi Cloud Translation API.

dự án moja trên toàn cầu

Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.

Tóm tắt dự án

Tổ chức nguồn mở:: moja global
Người viết nội dung kỹ thuật:: Tlazypanda
Tên dự án:: Tài liệu hướng dẫn làm quen với kỹ thuật cho FLINT
Độ dài dự án:: Thời hạn tiêu chuẩn (3 tháng)

Mô tả dự án

Tài liệu về Hướng dẫn làm quen với kỹ thuật dành cho FLINT để hướng dẫn người đóng góp mới làm quen với kỹ thuật để họ có thể dễ dàng bắt đầu với sự hỗ trợ tối thiểu từ các nhà bảo trì.

Vấn đề về dự án

Sau đây là danh sách các vấn đề quan trọng nhất liên quan đến tài liệu hiện tại: – Các phần hướng dẫn thiết lập cục bộ không được sắp xếp hợp lý, khiến người đóng góp mới khó bắt đầu. – Nhiều kho lưu trữ của FLINT thiếu tài liệu về mục đích của chúng và không được liên kết với nhau, khiến người mới khó xác định được kho lưu trữ nào cần cài đặt. – Việc cài đặt Windows được ghi chép đầy đủ nhưng tài liệu cài đặt dựa trên Linux có chỗ cần cải thiện. – Quy trình làm việc Git hiện không có trong tài liệu

Giải pháp Đề xuất

Đề xuất này giới thiệu một giải pháp hướng dẫn người đóng góp mới bằng quy trình làm quen với kỹ thuật để người đóng góp mới có thể dễ dàng bắt đầu với mức độ hỗ trợ tối thiểu từ người duy trì. Bạn có thể làm được việc này bằng cách tái cấu trúc tài liệu hiện tại để phù hợp với người mới bắt đầu, đồng thời duy trì một kho lưu trữ độc lập trung tâm cho tất cả tài liệu hiện có. Dự án này được chia thành 3 giai đoạn:- – Xem xét tài liệu hiện có và tái cấu trúc: Mục tiêu của giai đoạn này là xem lại hướng dẫn hiện tại và tái cấu trúc hướng dẫn sao cho ngắn gọn và dễ hiểu đối với những cộng tác viên mới. Tài liệu này cũng cần được chỉnh sửa cho phù hợp với người mới bắt đầu hơn bằng cách thêm huy hiệu, biểu tượng cảm xúc và thông tin về những vấn đề được gắn nhãn là thẻ chỉ cho phép người mới sử dụng lần đầu hoặc chỉ cho phép người dùng xem lần đầu tiên. – Tạo kho lưu trữ tài liệu độc lập tập trung: Mục tiêu của giai đoạn này là liên kết tất cả tài liệu có sẵn theo thứ tự tuần tự hợp lý tại một kho lưu trữ độc lập. Việc này bao gồm việc sắp xếp các nguyên tắc đóng góp, hướng dẫn thiết lập dự án và hướng dẫn từng bước. – Thêm quy trình làm việc dành cho Nhà phát triển và trang web cộng đồng cho nhà phát triển mới: Mục tiêu của giai đoạn này là thêm Quy trình làm việc của Nhà phát triển, trong đó có nguyên tắc đóng góp git và kiến trúc công nghệ của dự án cùng với nguyên tắc kiểm thử và đảm bảo chất lượng. Trang web cộng đồng đề xuất sẽ là một ứng dụng trang đơn hiển thị quy trình làm việc, các vấn đề dành cho người mới mà cộng tác viên mới có thể xác nhận và danh sách tất cả cộng tác viên. Giai đoạn 1: Xem xét tài liệu hiện có và tái cấu trúc:

Sửa đổi tài liệu hiện tại của các kho lưu trữ sau: – FLINT: Tài liệu hiện tại không chi tiết lắm và không cung cấp thứ tự tuần tự các thư viện điều kiện tiên quyết. Hướng dẫn từng bước được chia thành nhiều tệp PDF nhưng có thể được hợp nhất ở một nơi duy nhất theo cách ngắn gọn hơn. Ngoài ra, hướng dẫn cài đặt dành cho cửa sổ nhưng đối với việc cài đặt Linux, việc chuyển hướng đến kho lưu trữ FLINT.docker có thể có lợi. - FLINT.docker: Tài liệu hiện tại không cung cấp mục đích đằng sau việc thiết lập kho lưu trữ này nhằm cung cấp cài đặt Linux của FLINT thông qua docker. Hỗ trợ thông qua docker chỉ giới hạn ở Ubuntu 18.04 (Bionic Beaver) nhưng có thể mở rộng sang các bản phân phối dựa trên Linux khác. Tài liệu hiện tại cũng cần nhấn mạnh cách thức thiết lập tuần tự của các tệp dockerfile và cũng cần đủ thông tin về cách tạo từ tệp makefile. – FLINT.example: Tài liệu hiện tại không cung cấp mục đích của việc thiết lập kho lưu trữ này, đó là cung cấp ví dụ về cách sử dụng FLINT. Bạn có thể phân tách các lần chạy mẫu khác nhau tốt hơn bằng các hướng dẫn cụ thể để chạy các lần chạy đó. Chúng ta cũng cần liên kết kho lưu trữ này với kho lưu trữ FLINT chính của chúng ta để cung cấp cho người dùng một cách để điều hướng đến đây nhằm xem ví dụ đang hoạt động.

Bạn cần thêm các thông tin sau vào tài liệu hiện tại: – Sử dụng Git và GitHub: Trong đó có hướng dẫn từng bước về cách phát triển nhánh, sao chép và sau đó thiết lập luồng từ xa cho kho lưu trữ. Trang này cũng sẽ cung cấp thông tin về cách đặt lại cơ sở so với bản chính mới nhất và xử lý xung đột hợp nhất. – Huy hiệu và biểu tượng cảm xúc: Tài liệu hiện tại thiếu Huy hiệu và biểu tượng cảm xúc có thể giúp những người đóng góp mới cảm thấy được chào đón và thấy các vấn đề ít đáng lo ngại hơn. – Thông tin về vấn đề phù hợp với người mới bắt đầu/Bộ tính giờ lần đầu: Thông tin này sẽ giúp chuyển hướng cộng tác viên mới đến các vấn đề phù hợp với người mới bắt đầu và trang web cộng đồng. – Thông tin về kho lưu trữ Import-me: Kho lưu trữ Import-me đóng vai trò là mẫu cơ sở để bắt đầu bất kỳ kho lưu trữ Moja Global nào. Tài liệu hiện tại không đề cập đến tầm quan trọng của việc này. Bạn cần cập nhật kho lưu trữ này để đề cập đến kho lưu trữ Import-me và các bước chọn kho lưu trữ này làm mẫu khi tạo kho lưu trữ mới. Bạn cũng nên có một quy trình vững chắc để các lập trình viên đề xuất các tính năng bổ sung cho kho lưu trữ Import-me.

Giai đoạn 2: Tạo kho lưu trữ tài liệu độc lập trung tâm :

Công cụ dùng cho nền tảng lưu trữ:

Các công cụ được đề xuất cho nền tảng lưu trữ này là Read The Docs vì những lý do sau:- - Được xếp hạng cao trong số các nền tảng lưu trữ. – Tự động cập nhật khi đẩy thay đổi – Dễ dàng thiết lập và hỗ trợ khắc phục sự cố nhờ cộng đồng lớn sử dụng công cụ này – Tài liệu được định dạng bằng reStructuredText và đầu ra được biên dịch bằng Sphinx.

Sắp xếp tất cả nội dung theo tuần tự hợp lý:

Thứ tự đề xuất của nội dung như sau:- – Giới thiệu tài liệu dành cho nhà phát triển: Phần này giới thiệu về Moja Global và FLINT. – Đóng góp: Phần này sẽ bao gồm các tiểu mục "Cách đóng góp" (về mã/báo cáo lỗi/bản dịch/tài liệu/tổ chức sự kiện, v.v.) và "Nguyên tắc ứng xử". – Thiết lập phát triển: Phần này sẽ bao gồm các tiểu mục "Quy trình làm việc của Git và GitHub", "Cài đặt Windows", "Cài đặt Linux". – Quy trình làm việc của nhà phát triển: Phần này sẽ bao gồm nội dung thảo luận về các công cụ được tích hợp để kiểm thử và cách kiểm thử thủ công trên yêu cầu kéo của bạn cũng như nhiều nội dung khác được ghi lại trong giai đoạn tiếp theo. – Tham gia cùng chúng tôi: Phần này sẽ giới thiệu nhiều diễn đàn mạng xã hội, chẳng hạn như các kênh Slack để kết nối và làm việc với Moja Global.

Giai đoạn 3: Thêm quy trình làm việc của nhà phát triển và trang web cộng đồng cho những người đóng góp mới:

Tài liệu về quy trình làm việc dành cho nhà phát triển:

Tài liệu về quy trình làm việc dành cho nhà phát triển sẽ bao gồm các tiểu mục sau:

Kiến trúc/Ngăn xếp công nghệ được sử dụng và các mô-đun khác nhau trong mã: Tài liệu để làm quen với các cộng tác viên mới về ngăn xếp công nghệ đã triển khai, các thư viện và mô-đun khác nhau của cơ sở mã.
Công cụ tích hợp về mức độ phù hợp và kiểm thử: Giới thiệu những người đóng góp mới cho các công cụ quy trình CI/CD dùng để kiểm thử, bot Mức độ phù hợp và Kiểm tra chất lượng tự động sẽ chạy dựa trên mã của họ. Ngoài ra, hãy cung cấp cho họ nguyên tắc về người cần liên hệ nếu kiểm thử không thành công.
Các bot được dùng để hỗ trợ quy trình làm việc, ví dụ: Zulipbot: Thiết kế các mẫu nội dung để bot hiển thị và cung cấp Tài liệu để người dùng hiểu được bot, thậm chí cải thiện cấu hình của bot bằng cách đóng góp.
Kiểm thử và gửi yêu cầu kéo theo cách thủ công: Cung cấp tài liệu về cách kiểm thử yêu cầu kéo theo cách thủ công theo một số tiêu chuẩn nhất định và tải kết quả lên dưới dạng ảnh chụp màn hình/ảnh gif khi gửi yêu cầu kéo.
Nguyên tắc về yêu cầu lấy dữ liệu xem xét mà người đóng góp phải tuân theo: Nguyên tắc gắn thẻ một số nhóm nhất định để xem xét và thêm các nhãn, chẳng hạn như "cần xem xét" vào yêu cầu lấy dữ liệu để cho phép người duy trì phản hồi.

Trang web cộng đồng:

Trang web cộng đồng sẽ có các tính năng sau:-

Thông tin về Quy trình công việc của chúng tôi: Quy trình làm việc sẽ bao gồm một loạt hành động mà một cộng tác viên mới có thể bắt đầu, tức là: xác nhận vấn đề trong bộ tính giờ đầu tiên, tiếp theo là tạo vấn đề bộ hẹn giờ đầu tiên cho người khác và trợ giúp người khác bằng cách cung cấp phản hồi và xem xét yêu cầu kéo của họ.
Danh sách các vấn đề chỉ dành cho người mới: Danh sách các vấn đề dành riêng cho người mới tham gia hoặc người mới đóng góp.
Danh sách vấn đề cũ: Danh sách các vấn đề chưa được xử lý trong một thời gian dài và do đó, các cộng tác viên có thể chọn.
Danh sách cộng tác viên: Danh sách cộng tác viên đã đóng góp cho kho lưu trữ Moja Global cho đến thời điểm hiện tại.
Người đóng góp gần đây: Danh sách những người đóng góp gần đây đã đóng góp cho kho lưu trữ Moja Global.
Đường liên kết để tham gia diễn đàn trò chuyện: Thông tin và đường liên kết để tham gia cộng đồng Slack nhằm giải đáp thắc mắc của họ cũng như trao đổi thêm về các dự án.