Best
practice in release management for open source projects
By Sander van der Waal,
Published: 26 October 2010, Reviewed: 12 November 2012
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ở (bản
dịch tiếng Việt) 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.
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.
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.
The
README.txt is where 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 where to find more information.
These
files are a reference for users recieving the new release to find out
what has changed from 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 where to get the various
distributions and where 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 from 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 where to find your project’s
version control logs.
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 from each upstream
project you use, and including it in your own.
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.
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 from 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 create
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.
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 created 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 created 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.
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.
Compressed distributions unpack correctly
Documentation is readable
Licences for libraries are distributed together with any applicable
NOTICEs
Licences comply with project policy
LICENCE and NOTICE documents contain required sections
All text files contain correct licence header
Files with licences other than the main project licence are mentioned
in LICENCE
All file headers comply with project policy
A meaningful readme.txt document is present in all distributions
LICENCE and NOTICE files are present in all distributions
A meaningful readme.txt document is present
Build instructions exist and the source builds using these
instructions
Licence headers are correctly applied
There are no version control files in the distribution
The source is exported from a tag from the version control system
KEYS file contains signing key
The key has been uploaded to regular public key servers
Dịch: Lê Trung Nghĩa
Không có nhận xét nào:
Đăng nhận xét
Lưu ý: Chỉ thành viên của blog này mới được đăng nhận xét.