Trên thư viện mã nguồn mở

Bài đăng này đã không được cập nhật trong 6 năm

Mở đầu

Thật dễ dàng để có thể sở hữu một thư viện mã nguồn mở, chỉ cần một chút thời gian để làm việc này. Tất cả những gì bạn cần là một kho chứa mã nguồn được lưu trữ ở đâu đó (Github, Bitbucket, ...) phải không nào? Không hẳn, trên thực tế, nó sẽ giúp ích hơn cho mọi người nếu bạn chăm chút hơn cho thư viện của mình. Hãy cùng xem làm thế nào để làm việc đó.

README

Tệp README là tệp đầu tiên trong thư viện của bạn. Bạn phải có nó! Tệp này phải chứa tên và mô tả ngắn của thư viện của bạn. Xem phần mô tả này tuần tự từng bước một.

Sau đó là cách sử dụng. Mô tả cách sử dụng thư viện của bạn bằng cả lời văn và đoạn mã. Thêm ảnh chụp màn hình hoặc GIF. Hãy diễn tả chi tiết hết sức có thể. Đây là tài liệu thư viện của bạn, và phần lớn thời gian dành cho thư viện, đây sẽ là tài liệu duy nhất bạn cung cấp.

Viết phần hướng dẫn sử dụng đầu tiên không phải là sự lựa chọn ngẫu nhiên. Tệp README nên là thứ đầu tiên dẫn dắt người tìm hiểu, sau đó họ sẽ sử dụng thư viện của bạn và đóng góp thêm (hoặc không).

Phần thứ ba mà bạn phải thêm vào là hướng dẫn cài đặt. Phần này đi vào chi tiết việc cài đặt một cách nhanh chóng. Nếu bạn có hai hay nhiều cách cài đặt, hãy mô tả cách mà bạn cho nó là tốt nhất, sau đó hãy giải thích thêm những cái khác sau.

Bạn cũng có thể thêm phần yêu cầu bắt buộc như phiên bản OS, thư viện khác, ...

Phần thứ tư là đóng góp. Nó có thể được thay thế bằng việc sử dụng tệp CONTRIBUTING. Giải thích làm thế nào để đọc hiểu thư viện của bạn, làm thế nào để báo lỗi hoặc gợi ý thêm chức năng. Điều quan trọng cần viết đầy đủ ở đây là giải thích rõ những nguyên tắc để tránh phải hỏi từng dòng mã trong pull requests mà bạn nhận được.

Bạn cũng phải thêm phần kiểm thử. Giải thích làm thế nào để cài đặt công cụ kiểm thử thích hợp, thiết lập test suite và chạy test.

Thêm nữa, bạn có thể thêm phần chi phí nếu bạn sử dụng dịch dụ mất phí của bên thứ 3 hoặc liệt kê các cộng sự, những người đồng tác giả, đóng góp cho thư viện.

Bạn phải thêm một bộ nguyên tắc ứng xử vì sự thiếu tôn trọng trong mã nguồn mở là không thể chấp nhận và đây là một cách dễ thực hiện để giải quyết vấn đề. Các hành vi bất lịch sự, thiếu tôn trọng phải bị cấm. Chúng ta phải làm rõ ràng những nguyên tắc này, chẳng hạn như thêm một tệp CODE_OF_CONDUCT.md

Phần cuối cùng nhưng không kém phần quan trọng, đó là giấy phép phát hành!

Đây là một mẫu tham khảo:

project-x
=========

project-x is a better way to achieve this and that, by leveraging the new API,
blablabla.

## Usage

...

## Installation

...

## Requirements

...

## Contributing

See CONTRIBUTING tệp.

## Running the Tests

...

## Credits

...

## Contributor Code of Conduct

Please note that this project is released with a [Contributor Code of
Conduct](http://contributor-covenant.org/). By participating in this project
you agree to abide by its terms. See CODE_OF_CONDUCT tệp.

## License

project-x is released under the MIT License. See the bundled LICENSE tệp for
details.

Như bạn thấy, tôi đã dưới thiệu hai tệp trong ví dụ trên: LICENSE và CONTRIBUTING. Tôi đã đề cập đến CONTRIBUTING. Vậy còn tệp LICENSE thì sao?

LICENSE

Tôi sẽ không so sánh tất cả các giấy phép, bạn hãy tự tra cứu thứ phù hợp. Nó cung cấp những thông tin hữu ích liên quan đến giấy phép sử dụng thư viện của bạn bằng những từ ngữ đơn giản.

Tôi có xu hướng sử dụng giấy phép MIT vì nó rất tự do. Lời khuyên của tôi ở đây là hãy nhìn vào cộng đồng của bạn và chọn một những cách thích hợp nhất. Ví dụ, trong cộng đồng Symfony2 (Một PHP Framework), hầu hết các thư viện được phát hành theo MIT. Tuy nhiên, những dự án Java thường được phát hành theo Apache License 2.0.

Theo báo cáo gần đây, phần lớn những dự án trên Github không có giấy phép mã nguồn mở. Điều này thật tồi tệ, bạn phải có giấy phép ngay cả khi nó là giấy phép của Beeware.

Ngay cả khi bạn đã có một thư viện với tài liệu đầy đủ và giấy phép, bạn vẫn chưa chắc có một thư viện tốt cho cộng đồng. Dưới dây, tôi đưa ra cái nhìn tổng quan về những gì tôi cho là quan trọng trong các dự án mã nguồn mở.

Write Tests & Automate

Dự án mã nguồn mở là cách để viết code đẹp mà không có thời hạn và cũng không có khách hàng. Lưu ý rằng các thư viện cho thấy bạn có thể làm gì, thư viện của bạn chính là danh thiếp cho bạn.

Viết tests thật nhiều. Làm sao có thể mong muốn mọi người đóng góp cho thư viện của bạn nếu bạn không viết test suite? Vì vậy, viết test và sử dụng Travis CI. Tất cả mọi thứ được viết trong tệp .travis.yml mô tả làm sao để chạy tests. Nó cũng là một cách để tài liệu hóa việc chạy tests.

Thêm nữa, hay thiết lập một bức ảnh trạng thái vào tệp README.md.

Hãy nhìn qua công cụ online ví dụ như Scrutinizer dành cho PHP và JavaScript,... Tự động hóa nhiều nhất bạn có thể.

Be Standard

Điều quan trọng là phải tìm được công cụ thích hợp cho thư viện của bạn. Nhìn lại vào cộng đồng mà bạn đang tham gia và chọn công cụ được nhiều người dùng. Với PHP, chúng ta dùng Composer để quản lý các thư viện. Đừng lãng phí thời gian với PEAR hoặc cái gì đó tương tự, hãy dùng Composer. Nếu bạn viết thư viện cho Node.js, đăng ký nó trên npm. Với Ruby, đó là gem và NuGe cho C#...

Một ví dụ khác, Symfony2 thêm hướng dẫn sử dụng trong thư mục Resource/doc. Đó chính là quy ước. Đừng lặp lại những hướng dẫn. Thay vào đó, hãy tạo ra những liên kết để nhanh chóng mở được tài liệu hướng dẫn từ README.md.

Manage Issues & Releases

(GitHub)[https://github.com/], (CodePlex)[https://archive.codeplex.com/] hoặc bất cứ dịch vụ gì bạn muốn, họ cung cấp "issue tracker".

Nếu bạn sử dụng Github, đừng lãng phí thời gian với Wiki. Tôi chưa bao giờ tìm được quy trình như vậy. Thay vào đó, dùng tệp README cho tài liệu hướng dẫn, hoặc liên kết đến trang chủ nơi chứa hướng dẫn cụ thể. Sử dụng GitHub issues để quản lý những cột mốc và dựa vào nhãn để biết vấn đề của bạn.

Hơn nữa, cố gắng phản hồi tất cả issues, sớm nhất có thể... Nhưng hãy cẩn trọng, quản lý thời gian của bạn. Vui vẻ với tất cả mọi người, và dành thời gian cho những người mới. Nó giá trị học tập "how to maintain a successful open source project".

Một lời khuyên khác là phát hành thường xuyên những phiên bản. Nói chuyện, thảo luận về phiên bản đó, hãy tuân thủ Sematic Versioning Specification.

Sau đó, cập nhật tệp CHANGELOG để giúp mọi người biết được những thay đổi. Nếu có sự thay đổi không tương thích với phiên bản trước, hãy viết một tệp UPGRADE để chỉ dẫn việc nâng cấp phiên bản mới.

You Need Feedback

Lý do chính tại sao tôi sử dụng mã nguồn mở là tôi có thể học được rất nhiều từ những phản hồi tích cực từ người dùng. Vì vậy, bạn cần được phản hồi, tôi cần phản hồi, tất cả mọi người đều cần phản hồi. Chia sẻ dự án của bạn trên Twitter, Hacker News và nhiều hơn nữa. Chia sẻ thật nhiều để mọi người biết đến thư viện của bạn không phải vì nó "xuất sắc" mà vì mọi người có thể bình luận về nó.

Sử dùng GitHub pages để tạo website cho thư viện của bạn, mua tên miền nếu bạn muốn.

Hire People

Một khi thư viện của bạn đã trở lên phổ biến, một việc quan trọng đó là vinh danh những người đã giúp đỡ bạn. Đó là một trải nghiệm tuyệt vời. Và nó sẽ giúp bạn có thêm nhiều thời gian cho những dự án khác (hay chính là kế hoạch "thống trị thế giới" của bạn)

Conclusion

Một thư viện mã nguồn mở không chỉ đơn giản là công khai mã nguồn. Bạn cần một vài thứ khác để giúp nó có thể sử dụng được và được yêu thích. Tài liệu hóa dự án của bạn chỉ ra rằng bạn có thể dạy, và bạn có thể tìm những từ thích hợp để giải thích một điều gì đó. Hơn nữa, nó chỉ ra rằng, bạn thực sự nghiêm túc với những thứ bạn làm.

Đừng quên thêm tests cho thư viện của bạn, nếu không thể làm nó ở cơ quan, hãy làm nó ở nhà. Dừng quên giấy phép phát hành, không có lý do nào để không làm việc này.

Nó thực sự tốt cho những dự án mã nguồn mở, nhưng tránh hội chứng NIH. Đóng góp càng nhiều càng tốt, mã nguồn mở thực sự không tồn tại.

Thư viện/dự án của bạn:

Phải có README.md tệp bao gồm tên, mô tả, những phần sau: Usage, Installation, Contributing, Testing và License.
Phải có Code of Conduct.
Phải có License
Phải có thể tests
Phải tuân theo tiêu chuẩn hoặc phù hợp với cộng đồng.

Bạn: