Thực tiễn tốt nhất trong quản lý phát hành các dự án nguồn mở

Thứ hai - 20/05/2013 05:51

P { margin-bottom: 0.21cm; }A:link { }

Best practice in release management for open source projects

By Sander van der Waal, Published: 26 October 2010, Reviewed: 12 November 2012

Theo: http://www.oss-watch.ac.uk/resources/releasemanagementbestpractice

Bài được đưa lên Internet ngày: 12/11/2012

Lời người dịch: Các dự án phần mềm tự do nguồn mở hầu hết đều theo phương châm “PHÁT HÀNH SỚM, PHÁT HÀNH THƯỜNG XUYÊN” và về mặt kỹ thuật, để có khả năng làm được việc đó, dự án cần tới phần mềm kiểm soát phiên bản - kiểm soát phát hành. Khi phát hành phiên bản, bạn cần tuân thủ hàng loạt công việc theo một qui trình được kiểm soát, kể cả công việc ký vào phần mềm phát hành đó, để đảm bảo an ninh cho việc tải về của những người sử dụng. Bài viết này thực sự là rất cần cho tất cả những ai đang quản lý một dự án PMTDM ở Việt Nam hiện nay.

Quản lý phát hành là về việc quản lý qui trình xây dựng, đóng gói và phân phối phần mềm để tiêu dùng. Trong quản lý phát hành các dự án nguồn mở chúng tôi giải thích qui trình của quản lý phát hành của các dự án phần mềm nguồn mở (PMNM). Trong tài liệu này chúng tôi sẽ tập trung vào một số thực tiễn tốt nhất trong quản lý phát hành và sẽ cung cấp một danh sách chọn để giúp cho bạn xác định và tối ưu hóa qui trình quản lý phát hành của dự án.

Phát hành sớm, phát hành thường xuyên

Thậm chí nếu bạn không có những người sử dụng ngoài độ dự án cốt lõi, thì việc tạo một phát hành ở giai đoạn sớm của dự án sẽ đảm bảo rằng, ở thời điểm khi nó còn dễ làm thế, bạn xây dựng các công cụ và hạ tầng cho việc thực hiện các phát hành nhanh. Nếu bạn để điều này tới tận sau này, thì kho mã sẽ tăng lên về kích thước và phức tạp. Điều này làm cho nó khó hơn để thiết lập qui tình xây dựng.

Hơn nữa, trong khi mã nguồn là sẵn sàng một cách tự do và được phát triển theo một cách thức mở, thì các lập trình viên và những người sử dụng tiềm tàng thường sẽ muốn có khả năng đánh giá nó nhanh và dễ dàng. Bạn vì thế nên phát hành phần mềm của dự án của bạn thường xuyên, và ở dạng mà dễ dàng truy cập được và có thể được các lập trình viên trong bất kỳ môi trường nào sử dụng. Bằng cách làm như vậy, bạn sẽ làm cho nó dễ dàng hownn cho mọi người để đóng góp. Nếu bạn xử trí nó đủ sớm, thì bạn sẽ thấy sự tạo ra một hệ thống xây dựng - và - phát hành bán tự động đơn giản hợp lý.

Phát hành sớm, phát hành thường xuyên là một câu châm ngôn nổi tiếng trong phát triển nguồn mở. Một số lý do cuốn hút hơn cho điều này là:

khuyến khích các ý kiến phản hồi sớm và thường xuyên
đưa ra sự truy cập dễ dàng tới các tính năng mới nhất và tốt nhất
xây dựng lòng tin của các lập trình viên
chỉ ra hoạt động thật của dự án
tạo thuận lợi cho con đường nâng cấp có khả năng quản lý được cho những người sử dụng

Nhiều dự án không phát hành sớm, nói rằng mã là chưa hoàn chỉnh, rằng nó cần phải được làm trơn tru một chút hoặc nó còn chưa được kiểm thử đầy đủ. Thường là hoàn toàn đáng sợ khi phát hành phần mềm mà được xem là chưa sẵn sàng. Tuy nhiên, sự thật là các ứng dụng hiếm khi được hoàn thành, mã luôn có thể được đánh bóng và cách thử tốt nhất là đưa nó vào trong tay của những người áp dụng nó sớm.

Phát hành sớm, phát hành thường xuyên là một phần quan trọng của việc xây dựng dự án nguồn mở bền vững. Các phát hành nằm trong những người sử dụng, những người sử dụng đôi khi trở thành những người đóng góp, và những người đóng góp làm cho dự án mạnh hơn. Con đường đi xuống của việc phát hành sớm và thường xuyên, tuy nhiên, là bạn cần phải quản lý các kỳ vọng của những người sử dụng của bạn. Hãy rõ ràng về tình trạng thật của phát hành của bạn và lôi kéo sự chú ý của những người sử dụng tới bất kỳ lỗi được biết nào trong tài liệu của bạn.

Nhiều dự án phát hành trong chế độ giấu giếm cho tới khi hoàn tất tính năng hợp lý. Đó là, họ không tìm cách quảng cáo sự hiện diện của họ và không cung cấp cho các website có trọng tâm hướng vào người sử dụng, vì thế về cơ bản lọc đi những người áp dụng sớm. Việt phát hành dự án của bạn ở chế độ giấu giếm sẽ cho phép những người thực sự có quan tâm trong công việc của bạn tìm thấy được bạn và làm quen một cách dễ dàng. Mặt khác, bạn ít có khả năng hơn để lôi cuốn những người sử dụng đầu cuối mà không có quan tâm trong các dự án ở giai đoạn phát triển sớm.

Thực tiễn phổ biến để chuyển các phát hành dựa vào thời gian càng sớm càng tốt. Việc tạo ra một chu kỳ phát hành (như việc phát hành mỗi 6 tháng một lần) làm lợi cho cộng đồng bằng việc cung cấp các thời hạn chót cho những người đóng góp, và cho phép những người sử dụng lên kế hoạch cho các bản nâng cấp.

Đưa ra tài liệu phù hợp

Những người sử dụng mong đợi tìm thấy một tập hợp tối thiểu các tài liệu trong thư mục gốc của phát hành. Trong phần này chúng tôi mô tả các tài liệu đó, được liệt kê theo tên tệp mà chúng thường xuất hiện. Phải chắc chắng là tất cả tài liệu được đọc kỹ ròi và, trong trường hợp của những điều như là các chỉ dẫn cài đặt, cũng phải được kiểm thử.

README.txt

README.txt là nơi mà người sử dụng sẽ tới đầu tiên, một khi họ đã tải về phân phối của bạn. Tệp này nên trao những thông tin tối thiểu nhất về phát hành và cách để bắt đầu làm việc với nó. Ít nhất, nó nên gồm các chỉ dẫn về cách để làm quen và các chi tiết đâu là nơi tìm các thông tin hơn nữa.

Các lưu ý phát hành (RELEASE-NOTES) và những thay đổi

Các tệp đó là một tham chiếu cho những người sử dụng nhận phát hành mới tìm ra những gì đã thay đổi từ phiên bản trước. Trong khi không được xác định chặt chẽ thông tin nào nên có trong tệp đó, thì bạn nên đảm bảo bạn tuân thủ các thực tiễn của các dự án tương tự, như các dự án được quỹ y hệt như của bạn quản lý.

Các lưu ý phát tán nên có một mô tả dự án và tổng quan của những gì phát tán mới này cung cấp. Chúng nên không dudwa ra thông tin thay đổi chi tiết, mà nên liệt kê đầu đề những thay đổi mà sẽ khuyến khích những người suwrr dụng nâng cấp. Chúng có thể bao gồm các tính năng mới và các sửa lỗi chính trong phát hành mới, cũng như chi tiết hóa bất kỳ vấn đề được biết nào với phát hành.

Tài liệu này cũng nên có thông tin về địa điểm để có các phân phối khác nhau và địa điểm để tìm thêm thông tin, khi nó thường sẽ được sử dụng khi công bố một phát hành ra thế giới bên ngoài. Đó là, nó nên là một tài liệu có ý nghĩa thậm chí khi không nằm trong một phân phối.

Tệp cho những thay đổi (tệp CHANGES) là một tài liệu mô tả các sửa lỗi, các tính năng mới và các thay đổi API được thấy trong phát hành này. Các lưu ký từ hệ thống kiểm soát phiên bản có thể được sử dụng để thu thập các thay đổi, nhưng điều này có thể làm cho quá chi tiết đối với mọi thứ. Đây là một cơ hội tốt cho chỉ một vấn đề hoặc tính năng, và các thông điệp neenn rõ ràng và súc tích.

Một số công cụ đưa ra phương tiện cho việc quản lý các tài liệu thay đổi một cách độc lập của hệ thống kiểm soát phiên bản. Điều này cho phép kiểm soát nhiều hơn đối với những gì xuất hiện trong tài liệu các thay đổi của bạn và vì thế làm cho tài liệu hữu dụng hơn đối với những người sử dụng. Đối với những người sử dụng mà có quan tâm chi tiết hơn, bạn cũng có thể đưa vào thông tin nơi để tìm các lưu ký kiểm soát phiên bản của dự án của bạn.

GIẤY PHÉP VÀ LƯU Ý

Một tệp có tên là LICENCE (GIẤY PHÉP) trong thư mục gốc root nên chỉ rõ ràng giấy phép đang sử dụng. Bạn cũng có thể yêu cầu một văn bản LƯU Ý (NOTICE), nhưng điều này sẽ phụ thuộc vào các giấy phép của các thư viện bạn đưa vào trong phân phối của bạn. Một số giấy phép đòi hỏi rằng bạn tin tưởng các tác giả của bất kỳ mã nào mà bạn đã đưa vào theo giấy phép đó. Điều này là đơn giản như việc sao chép các nội dung của các tệp NOTICE từ từng dự án dòng trên bạn sử dụng, và đưa nó vào trong của riêng bạn.

Chữ ký cho các phát hành của bạn

Việc phát hành các tệp thực thi thông qua website (hoặc một đặt chỗ hosting) của riêng bạn không hoàn toàn không có rủi ro. Nếu ai đó can thiệp được với các tệp nhị phân của bạn, ví dụ bằng việc bổ sung thêm phần mềm độc hại vào mã, thì những người sử dụng của bạn có thể tải về các mã độc vào các máy tính của họ bằng việc sử dụng phần mềm của bạn. Tất nhiên bạn có thể muốn ngăn chặn điều đó. Chúng tôi sẽ tập trung vào 2 cách thức làm điều này: bổ sung một sự tổng kiểm tra (checksum) cho sự tải về và làm điều này sẵn sàng như một tệp riêng rẽ, và ký phát hành với một chữ ký PGP.

Bổ sung thêm một tổng kiểm tra cho tải về của bạn

Vài thuật toán từng được phát triển để tạo ra một tổng kiểm tra băm cho một tệp, ví dụ họ MD5 hoặc SHA (SHA1, SHA128, SHA512). Mục đích của việc tạo ra digest thông điệp này là để đảm bảo rằng tệp mà bạn tải về chính xác y hệt tệp mà đã được chào, sao cho không một byte nào có thể khác được. Điều này sẽ giúp bạn không chỉ ngăn chặn được sự vi phạm từ những người bên ngoài, mà còn dò tìm ra các lỗi kỹ thuật trong khi truyền tệp đó.

Một số webiste đặt chỗ hỗ trợ điều này bằng việc tạo ra một tổng kiểm tra cho bạn và làm điều này tự động sẵn sàng cho những người sử dụng mà tải phần mềm của bạn về. Google Code làm điều này. Chúng cung cấp các băm SHA1 cho tất cả các tải về mà bạn làm cho sẵn sàng thông qua phần tải về của dự án được đặt trên Google Code.

Một công cụ dễ dàng, đơn giản để sử dụng để bạn tự tạo các băm là ứng dụng nguồn mở GNU Privacy Guard (GPG). Nó hỗ trợ các thuật toán MD5 cũng như SHA. Qui trình là khá đơn giản. Bạn tạo tệp tổng kiểm tra cho bản tải về được sinh ra và tải chúng lên tới website của bạn. Người sử dụng có quan tâm trong bản tải ề cũng tải về tổng kiểm tra và sử dụng một công cụ tương tự GPG để kiểm tra xem liệu tổng kiểm tra có đúng hay không. Nói chung, khi tạo một khóa băm, bạn nên sử dụng các thuật toán với khóa băm dài nhất, vì chúng là an ninh nhất. Với sự thô bạo có khả năng phá tất cả các khóa băm, nhưng một khóa ngawnns như MD5 là dễ dàng hơn nhiều so với phá một khóa như SHA512.

Ký phát hành của bạn bằng chữ ký PGP

Cách khác để bảo vệ các tệp nhị phân được phát hành của bạn là ký chúng với một chữ ký PGP. Bạn có thể sử dụng cùng công cụ y hệt (GPG) cho điều đó. Khi bạn bắt đầu sử dụng nó, bạn trước hết cần tạo ra một sự kết hợp khóa công khai/riêng. Bạn sau đó sẽ phải công bố khóa công khai trong một tệp. Thông thường, có mọt tệp KEYS (KHÓA) cho toàn bộ dự án, có chứa các khóa công khai của tất cả các lập trình viên thích hợp. Sau đó, bạn có thể ký một nhị phân phát hành bằng việc sử dụng khóa riêng của bạn, nó sẽ là một tệp chữ ký. Một tệp chữ ký hoàn toàn tương tự với một tệp khóa băm.

Bây giờ bất kỳ ai cũng có thể tải về nhị phân, khóa công khai của bạn và tệp chữ ký, cũng có thể kiểm tra liệu chữ ký đó có khớp với khóa công khai và nhị phân hay không. Điều này sẽ đảm bảo rằng tệp được tải về là y hệt tệp từng được bạn, người quản lý phát hành, tạo ra. Các chữ ký PGP có thể cung cấp một mức bảo vệ dư thêm bằng việc xác định rằng sự kết hợp chữ ký công khai/riêng mà đã ký nhị phân quả thực được kết nối tới cá nhân đó. Nó làm việc theo một cách thức phi tập trung (đối nghịch với phương pháp PKI, mà cần một cơ quan chứng thực cấp chứng chỉ). Một khi bạn đã tạo được các khóa của riêng bạn, thì bạn có thể trao đổi khóa công cộng của bạn với những người sử dụng khác và vì thế thêm chúng vào web tin cậy của bạn. Bạn làm thế bằng việc ký các khóa lẫn của nhau. Bạn nên thực sự làm điều này một mình, có lẽ ở một hội nghị, để chắc chắn rằng bạn đang làm việc đó với ai.

Danh sách chọn

Danh sách chọn bên dưới sẽ giúp bạn đảm bảo rằng mọi điều bạn cần làm trong một phát hành đã được thực hiện. Các dự án riêng rẽ sẽ cần phải bổ sung thêm một số kiểm tra khác, như đây là điểm khởi đầu tốt.

Các phân phối

Giải nén các phân phối được nén một cách đúng đắn
Tài liệu là đọc được
Các giấy phép cho các thư viện được phân phối cùng với bất kỳ LƯU Ý áp dụng nào
Các giấy phép tuân thủ với chính sách của dự án
Các tài liệu GIẤY PHÉP và LƯU Ý có các phần được yêu cầu
Tất cả các tệp văn bản có đầu đề giấy phép đúng
Các tệp với các giấy phép khác với giấy phép của dự án chính được nêu trong GIẤY PHÉP
Tất cả các đầu đề tuân thủ với chính sách của dự án

Các chế tác được phân phối

Tài liệu readme.txt có ý nghĩa hiện diện trong tất cả các phân phối
Các tệp GIẤY PHÉP và LƯU Ý hiện diện trong tất cả các phân phối

Phân phối nguồn

Tài liệu readme.txt có ý nghĩa là hiện diện
Xây dựng các chỉ dẫn tồn tại và xây dựng nguồn bằng việc sử dụng các chỉ dẫn đó
Các đầu đề giấy phép được áp dụng đúng
Không có các tệp kiểm soát phiên bản trong phân phối
Nguồn được xuất khẩu khỏi một thẻ tag từ hệ thống kiểm soát phiên bản

Các khóa OpenPGP

Tệp CÁC KHÓA có chứa khóa ký
Khóa được tải lên vào các máy chủ khóa công khai thông thường

Release management is about managing the process of building, packaging and distributing software for consumption. In release management in open source projects we explain the process of release management in open source software projects. In this document we will focus on some of the best practices in release management and will supply a checklist to help you define and streamline your project’s release management process.

Release early, release often

Even if you have no users outside the core project team, creating a release at an early stage of the project will ensure that, at a time when it is easy to do so, you build the tools and infrastructure for doing quick releases. If you leave this until later, the codebase will have grown in size and complexity. This makes it harder to set up the build process.

In addition, while the source code is freely available and developed in an open manner, potential developers and users will generally want to be able to evaluate it quickly and easily. You should therefore release your project’s software frequently, and in a form that is easily accessible and can be used by developers in any environment. By doing so, you will make it easier for people to contribute. If you tackle it early enough, you will find the creation of a semi-automated build-and-release system reasonably simple.

Release early, release often is a well-known mantra in open source development. Some of the more compelling reasons for this are that it:

encourages early and frequent feedback
provides easy access to the latest and greatest features
builds developer confidence
shows genuine project activity
facilitates a manageable upgrade path for users

Many projects resist releasing early, saying that the code is unfinished, that it needs to be polished a little or that it has not been fully tested yet. It is often quite scary releasing software that is not considered ready. However, the truth is that applications are rarely finished, the code can always be polished and the best way to test is to put it in the hands of early adopters.

Release early, release often is an important part of building a sustainable open source project. Releases result in users, users sometimes become contributors, and contributors make the project stronger. The downside of releasing early and often, however, is that you need to manage your user expectations. Be clear about the true status of your release and draw users’ attention to any known bugs in your documentation.

Many projects release in stealth mode until they are reasonably feature complete. That is, they do not seek to advertise their existence and do not provide user-focussed websites, thus naturally filtering for early adopters. Releasing your project in stealth mode will allow those really interested in your work to find you and get started easily. On the other hand, you are less likely to attract end users who are not interested in projects that are at an early stage of development.

It is common practice to move to time-based releases as soon as possible. Creating a predictable release cycle (such as releasing once every 6 months) benefits the community by providing deadlines for contributors, and allowing users to plan for upgrades.

Provide appropriate documentation

Users expect to find a minimal set of documentation in the root directory of a release. In this section we describe those documents, listed by the filenames they usually appear under. Make sure that all documentation is proofread and, in the case of things like installation instructions, tested as well.

README.txt

The README.txt is whe-re the users will go first, once they have downloaded your distribution. This should give the bare minimum of information on the release and how to start working with it. At the very least, it should include instructions on how to get started and details of whe-re to find more information.

RELEASE-NOTES and CHANGES

These files are a reference for users recieving the new release to find out what has changed f-rom the previous version. While it’s not strictly defined which information should be in which file, you should ensure you conform the the practices of similar projects, such as those managed by the same foundation as your own.

The release notes should contain a description of the project and an overview of what this new release provides. They should not provide detailed change information, but should list the headline changes that will encourage users to upgrade. These could include new features and major bugfixes in the new release, as well as detailing any known issues with the release.

This document should also contain information on whe-re to get the various distributions and whe-re to find more information, as it will often be used when announcing a release to the outside world. That is, it should be a meaningful document even when not located in a distribution.

The CHANGES file is a document describing the bug fixes, new features and API changes found in this release. Logs f-rom the version control system can be used to collect changes, but this can result in too detailed a view of things. For example, a spelling correction in the documents does not warrant an entry in the changes document. This is a good opportunity to reinforce the need for good commit messages: each commit should contain work for only one issue or feature, and messages should be clear and concise.

Some tools provide a means for managing change documents independently of the version control system. This allows much more control over what appears in your changes document and so makes the document more useful to users. For users who are interested in more detail, you could also include information of whe-re to find your project’s version control logs.

LICENCE and NOTICE

A file named LICENCE in the root directory should clearly indicate the licence in use. You may also require a NOTICE text, but this will depend on the licences of the libraries you include in your distribution. Some licences require that you credit the authors of any code that you have included under that licence. This is as simple as copying the contents of the NOTICE files f-rom each upstream project you use, and including it in your own.

Sign your releases

Releasing executables through your own (or a hosting) website is not entirely risk-free. If someone tampers with your binaries, for example by adding malware to the code, your users may be downloading malicious code to their computers by using your software. Of course you would want to prevent that. We will focus on two ways of doing this: adding a checksum to the download and making this available as a separate file, and signing the release with a PGP signature.

Adding a checksum to your download

Several algorithms have been developed to generate a hash checksum for a file, for example MD5 or the SHA family (SHA1, SHA128, SHA512). The purpose of creating this message digest is to ensure that the file you downloaded is exactly the same file that was offered, so not one byte can be different. This will help you to not only prevent infringement f-rom outsiders, but also detect technical errors in the transmission of the file.

Some code hosting websites assist with this by generating a checksum for you and making this automatically available for users who download your software. For example, Google Code does this. They provide SHA1 hashes for all downloads that you make available through the download section of a Google Code hosted project.

An easy, simple-to-use tool to generate hashes yourself is the open source application GNU Privacy Guard (GPG). It supports MD5 as well as several SHA algorithms. The process is fairly simple. You cre-ate the checksum file for the generated download and upload them both to your website. The user interested in the download also downloads the checksum and uses a tool similar to GPG to check if the checksum is correct. In general, when generating a hash key, you should use the algorithms with the longest hash key, as they are more secure. With brute force it is possible to break all hash keys, but a short key like MD5 is much easier to crack than one like SHA512.

Signing your release with a PGP signature

Another way to protect your released binaries is to sign them with a PGP signature. You can use the same tool (GPG) for that. When you start using it, you first need to generate a public/private key combination. You will then have to publish the public key in a file. Commonly, there is one KEYS file for the whole project that contains the public keys of all relevant developers. Next, you can sign a release binary using your own key, which will result in a signature file. A signature file is quite similar to a hash key file.

Now anybody who can download the binary, your public key and the signature file, can also check whether the signature matches the public key and the binary. This will ensure that the file that has been downloaded is the same file that has been cre-ated by you, the release manager. PGP signatures can provide an extra level of protection by identifying that the public/private key combination that signed the binary is indeed linked to the individual. It works in a decentralised way (as opposed to the PKI method, which needs a certifying authority). Once you have cre-ated your own keys, you can exchange your public key with other users and thereby add them to your web of trust. You do that by signing each other’s keys. You should really do this in person, perhaps at a conference, to make sure that you know who you are dealing with.

Checklist

The checklist below will help you to ensure that everything you need to do in a release has been done. Individual projects will need to add some other checks, but this is a good starting point.

Distributions

Compressed distributions unpack correctly