Phát hành mã nghiên cứu: GitHub nối Zenodo, CITATION.cff, giấy phép

Để mã nghiên cứu có DOI, đăng nhập Zenodo bằng GitHub, bật kho trong mục GitHub của Zenodo, rồi tạo một bản phát hành (release) trên GitHub; Zenodo tự lưu bản đó và cấp DOI. Thêm tệp CITATION.cff để người dùng biết trích dẫn thế nào, và tệp LICENSE để họ biết được làm gì.

Nhiều tạp chí yêu cầu khai báo nơi có mã phân tích. Một đường dẫn GitHub là chưa đủ: kho có thể bị sửa, đổi tên, xoá. Bản lưu trên Zenodo thì cố định, có DOI và được trích dẫn như một công trình. Bài này đi qua từng bước, từ chuẩn bị kho tới dòng khai báo trong bài báo.

Chuẩn bị kho trước khi phát hành

Kho sẽ được đóng băng đúng như lúc phát hành, nên dọn dẹp trước:

• README nêu mục đích, cách cài, cách chạy lại phân tích, nơi lấy dữ liệu, và bài báo liên quan.
• Tệp khoá môi trường như renv.lock hoặc environment.yml.
• Không còn đường dẫn cứng theo máy cá nhân, không còn khoá API, không còn dữ liệu nhạy cảm trong cả lịch sử.
• Tệp LICENSE ở thư mục gốc.
• Tệp CITATION.cff ở thư mục gốc.

Tích hợp GitHub của Zenodo chỉ làm việc với kho công khai. Nếu kho đang riêng tư, chuyển sang công khai trước khi phát hành, sau khi đã rà kỹ lịch sử.

Nối GitHub với Zenodo và tạo bản phát hành

Thao tác một lần cho mỗi kho:

1. Đăng nhập Zenodo, chọn đăng nhập bằng GitHub hoặc liên kết tài khoản GitHub trong phần cài đặt tài khoản.
2. Vào mục GitHub trong menu tài khoản Zenodo, bấm đồng bộ để Zenodo thấy danh sách kho, rồi bật công tắc cạnh kho muốn lưu trữ.
3. Sang GitHub, vào kho, chọn tạo bản phát hành mới trong mục Releases, tạo thẻ mới như v1.0.0, đặt tiêu đề và mô tả, bấm phát hành.
4. Chờ vài phút, quay lại mục GitHub trên Zenodo: bản phát hành đã thành bản ghi có DOI. Mở bản ghi để kiểm tác giả, mô tả, giấy phép.
5. Sửa siêu dữ liệu trên Zenodo nếu cần; lần sau dùng tệp CITATION.cff hoặc .zenodo.json để khỏi sửa tay.

Zenodo cấp hai loại DOI. Mỗi bản phát hành có DOI phiên bản riêng; ngoài ra có một DOI khái niệm (concept DOI) đại diện cho mọi phiên bản và luôn trỏ tới bản mới nhất. Trong bài báo, dẫn DOI phiên bản đúng với bản mã đã sinh kết quả; trong trang giới thiệu dự án thì dùng DOI khái niệm.

Viết tệp CITATION.cff

Tệp này để làm gì

CITATION.cff là tệp văn bản theo định dạng Citation File Format, khai cách trích dẫn phần mềm. Khi kho có tệp này, GitHub hiện nút trích dẫn kho ở thanh bên, cho chép trích dẫn dạng APA hoặc BibTeX. Zenodo cũng đọc tệp này để điền siêu dữ liệu bản ghi; nếu kho có cả .zenodo.json thì Zenodo ưu tiên tệp đó.

Các dòng tối thiểu

Tệp viết theo cú pháp YAML. Bốn trường bắt buộc: cff-version: 1.2.0, message: If you use this software, please cite it as below., title: Ma phan tich khao sat ho gia dinh, và khối authors: với mỗi tác giả một mục gồm family-names, given-names, có thể thêm orcid ghi ở dạng đường dẫn ORCID đầy đủ. Nên thêm version: 1.0.0, date-released: 2026-03-15, license: MIT, và doi sau khi có DOI khái niệm.

Trỏ về bài báo

Nếu muốn người dùng trích dẫn bài báo thay vì mã, thêm khối preferred-citation: mô tả bài báo, kiểu article, kèm tác giả, tạp chí, năm, DOI. Nút trích dẫn trên GitHub sẽ hiện bài báo. Kiểm tệp hợp lệ bằng công cụ cffconvert với tuỳ chọn --validate, hoặc dùng trình tạo trực tuyến cffinit.

Chọn giấy phép cho mã

Mã không kèm giấy phép thì về mặt pháp lý người khác không được phép dùng lại, dù kho công khai. Ba giấy phép phổ biến:

GitHub có sẵn trình chọn giấy phép khi tạo tệp tên LICENSE. Trước khi chọn, hỏi đơn vị chủ quản và bên tài trợ có quy định về quyền sở hữu trí tuệ không, nhất là đề tài có hợp đồng với doanh nghiệp. Nếu mã dựa trên thư viện GPL và bạn phân phối kèm thư viện đó, giấy phép của bạn cần tương thích.

Giấy phép cho mã và cho dữ liệu là hai chuyện

Mã dùng giấy phép phần mềm. Creative Commons khuyến cáo không dùng giấy phép CC cho phần mềm vì không xử lý chuyện sáng chế và phân phối mã nguồn.

Dữ liệu dùng giấy phép dữ liệu. CC BY 4.0 hoặc CC0 cho dữ liệu, đặt trong bản ghi dữ liệu riêng hoặc ghi rõ trong README nếu dữ liệu nằm chung kho mã.

Văn bản hướng dẫn, hình minh hoạ. Có thể dùng CC BY 4.0. Ghi trong README phần nào theo giấy phép nào nếu kho trộn nhiều loại.

Dữ liệu của bên thứ ba. Dữ liệu bạn lấy từ nguồn khác, như bộ điều tra của cơ quan thống kê hay cơ sở dữ liệu thương mại, không thuộc quyền bạn cấp phép. Không đưa vào kho; ghi trong README cách người dùng tự xin hoặc tải từ nguồn gốc, kèm phiên bản và ngày truy cập.

Mã chép từ nguồn khác. Đoạn mã lấy từ diễn đàn, sách hay kho khác có giấy phép riêng. Ghi nguồn trong chú thích ở đầu đoạn mã và kiểm giấy phép gốc có tương thích với giấy phép bạn chọn.

Những lỗi làm bản phát hành vô dụng

Phát hành kho không chạy được

Người tải về làm theo README mà báo lỗi ngay bước đầu là lỗi phổ biến nhất. Trước khi phát hành, sao chép kho sang một thư mục mới hoặc máy khác, làm đúng theo README từ đầu tới cuối. Chỗ nào phải làm thêm mà README không nói là chỗ cần viết bổ sung.

Tác giả trên Zenodo chỉ là tên tài khoản GitHub

Khi kho không có CITATION.cff hay .zenodo.json, Zenodo lấy thông tin từ GitHub và có thể chỉ ghi tên đăng nhập. Sửa lại trên Zenodo, rồi thêm tệp trích dẫn để các bản sau đúng ngay.

Mã trong kho khác mã đã chạy ra kết quả

Tiếp tục sửa mã sau khi chốt số liệu mà không phát hành bản mới, rồi dẫn DOI của bản cũ. Người đọc chạy lại sẽ ra số khác. Phát hành ngay khi chốt số liệu và ghi thẻ phiên bản trong bản thảo.

Dữ liệu đi kèm vi phạm cam kết

Kho mã chứa tệp dữ liệu mẫu chưa ẩn danh hết. Bản lưu Zenodo đã công bố thì rất khó gỡ; rà kỹ trước khi bấm phát hành.

Ghi mã vào bài báo thế nào?

Trong mục khai báo mã và dữ liệu, ghi theo mẫu: mã phân tích lưu trữ trên Zenodo với DOI phiên bản, kèm đường dẫn kho GitHub để theo dõi phát triển. Đồng thời đưa mã vào danh mục tài liệu tham khảo như một công trình: tác giả, năm, tên, phiên bản, Zenodo, DOI. Nhiều tạp chí và hướng dẫn trích dẫn phần mềm khuyến khích cách này để người viết mã được ghi nhận.

Thứ tự hợp lý khi nộp bài: phát hành bản v1.0.0 trước khi nộp để có DOI ghi vào bản thảo. Khi sửa theo phản biện, phát hành v1.1.0 và cập nhật DOI trong bản sửa. Nếu chưa muốn công khai mã khi bài đang bình duyệt, Zenodo cho tải lên thủ công và giữ bản ghi ở chế độ hạn chế hoặc đặt thời hạn cấm công bố; khi đó không dùng tích hợp GitHub được vì kho phải công khai.

Câu hỏi thường gặp