Viết về Capturia và ghi nhận đóng góp của OpenScreen
Tách nguồn gốc upstream, thay đổi cụ thể và kết quả đã kiểm tra qua tài liệu Capturia, thông báo giấy phép và ví dụ tính thời lượng GIF.
Khi giới thiệu một dự án kế thừa mã nguồn, hãy nêu nền tảng của nó rồi giải thích một đóng góp cụ thể bằng bằng chứng. Người đọc portfolio cần phân biệt được ai tạo ra phần nền tảng, phiên bản đang nói tới đã thay đổi gì và kết quả được kiểm tra ra sao. Đó là những câu hỏi riêng, và một ảnh chụp đẹp không trả lời được cả ba.
Với lập trình viên viết về một dự án điều chỉnh từ mã nguồn mở, Capturia là ví dụ cụ thể. README xác định rõ đây là một fork của OpenScreen, dựa trên OpenScreen v1.10.0 tại commit 70e30c1f, và phần lớn mã vẫn là công trình của OpenScreen. Tôi giữ mối quan hệ ấy ngay trong phần giới thiệu chính. Nội dung nghề nghiệp có ích nằm ở quyết định và thay đổi có thể xem xét, thay vì làm phần nền tảng biến mất khỏi câu chuyện.
Đặt nguồn gốc upstream cạnh tên dự án
Tại phiên bản Capturia được xem xét ở đây, lời ghi nhận được đặt nổi bật trước danh sách tính năng. README còn nói Capturia không liên kết với, không được bảo chứng hay hỗ trợ bởi OpenScreen, đồng thời hướng lỗi của Capturia tới trình theo dõi vấn đề riêng. Các chi tiết này cho người đọc biết phần mềm xuất phát từ đâu và trách nhiệm đối với bản kế thừa nằm ở đâu.
Một câu mở đầu phù hợp là: “Capturia là ứng dụng ghi và chỉnh sửa màn hình dựa trên OpenScreen mà tôi duy trì.” Sau đó có thể mô tả tính năng với bằng chứng riêng. Gọi nó là một bộ máy ghi hình được tự phát triển từ đầu sẽ hàm ý nguồn gốc khác. Chỉ liệt kê Electron, React và Rust mới mô tả công nghệ, chưa giải thích quan hệ quan trọng giữa hai dự án.
Hãy đặt lời ghi nhận đủ gần để nó vẫn xuất hiện trong các cách người khác thường xem portfolio. Thẻ dự án, README và phần trình bày ngắn có thể được đọc độc lập. Mỗi nơi cần đủ ngữ cảnh để tránh tạo ấn tượng sai. Trang dài có thể cung cấp liên kết upstream, phiên bản nền và đóng góp chi tiết; thẻ ngắn vẫn có thể ghi “dựa trên OpenScreen”.
Cách làm này phù hợp với Bộ quy tắc đạo đức của ACM: nguyên tắc 1.5 yêu cầu ghi nhận người tạo ra ý tưởng và sản phẩm, còn nguyên tắc 1.3 yêu cầu trung thực về năng lực và hạn chế. Không nguyên tắc nào buộc ta coi công việc bảo trì là vô giá trị. Chúng yêu cầu mô tả đúng giá trị ấy.
Mũi tên mô tả quan hệ dự án đã được tài liệu ghi nhận. Nó không quy mọi tệp hiện tại cho một người hay chứng nhận mọi thay đổi từ upstream đã được tích hợp đúng.
Tách bốn loại nhận định
Trước khi viết bài phân tích dự án, hãy lập bảng nhận định nhỏ. Sự phân biệt này ngăn bằng chứng cho một câu âm thầm trở thành bằng chứng cho câu rộng hơn.
| Nhận định | Bằng chứng có thể hỗ trợ | Điều vẫn cần xét riêng |
|---|---|---|
| Capturia phát triển từ OpenScreen | README và thông báo giấy phép tại phiên bản cố định | Tác giả của một thay đổi cụ thể |
| Dự án mô tả tính năng xuất GIF | Tài liệu tính năng tại phiên bản cố định | Một lần xuất thành công trên máy xác định |
| Một phiên bản đổi cách tính độ trễ GIF | Phần khác biệt thực tế trong mã nguồn | Tính đúng đắn của toàn bộ quy trình xuất native |
| Một quy trình cụ thể đã thành công | Lần chạy tái hiện được, kèm sản phẩm đầu ra và môi trường | Nền tảng, đầu vào hoặc bản phát hành khác |
Kho mã nằm trong tài khoản của tôi giúp xác định nơi chứa công việc. Chỉ điều đó chưa đủ chứng minh tôi tạo ra toàn bộ mã bên trong. Tương tự, commit xác định một thay đổi đã được ghi lại, nhưng sự hiện diện của nó chưa xác định ai thiết kế mọi phần, có ai cộng tác hoặc đã dùng hỗ trợ gì. Khi có thông tin, hãy mô tả đúng vai trò và sự cộng tác.
Bảng cũng giúp tránh phần tổng kết quá chung chung. “Làm về hiệu năng” rất khó đánh giá. “Đổi cách phân bố độ trễ theo đơn vị một phần trăm giây giữa các khung GIF” cho người xem cơ chế cụ thể để kiểm tra. Thay đổi ấy có cải thiện một lần xuất thực tế hay không vẫn cần phép kiểm tra tương ứng.
Theo dõi một thay đổi từ mã tới kết quả có phạm vi rõ
Phiên bản Capturia 8204e3e3 có thay đổi trong mã nguồn xuất GIF. So với commit cha, mã cũ dùng cùng độ trễ nguyên tính bằng centisecond cho mọi khung, lấy từ phép chia nguyên. Mã mới tính mỗi độ trễ bằng hiệu giữa hai mốc thời gian tích lũy liên tiếp đã được làm tròn.
Dùng 30 khung mỗi giây làm ví dụ có giới hạn. Một centisecond là một phần trăm giây. Bỏ phần lẻ của 100 / 30 cho ba centisecond mỗi khung. Ba mươi khung như vậy có tổng độ trễ được khai báo là 90 centisecond, dù khoảng thời gian nguồn dự kiến là một giây. Với 1.800 khung, cách tính ấy cho tổng 54 giây thay vì 60.
Cách tính tích lũy mới làm tròn thời gian lý tưởng ở từng ranh giới khung. Tại 30 khung mỗi giây, ba mốc tích lũy đầu là 3, 7 và 10 centisecond. Lấy hiệu cho độ trễ từng khung là 3, 4 và 3. Tiếp tục phân bố như vậy đạt 100 centisecond sau 30 khung và 6.000 sau 1.800 khung.
Các kết quả số học này đã được kiểm tra độc lập cho bài viết. Mã được xem xét cũng thêm kiểm thử cho nhiều tốc độ khung, với tổng thời lượng một giây và sáu mươi giây. Đọc các kiểm thử cho biết kho mã yêu cầu chúng kiểm tra điều gì; việc đó không chứng minh bộ kiểm thử native đã được chạy tại đây.
Cần phân biệt độ trễ khai báo với hành vi phát quan sát được. Trình xem có thể diễn giải hoặc giới hạn các độ trễ nhỏ, và mã nguồn cũng có cách xử lý độ trễ tối thiểu riêng. Phép tính cho 30 khung không chứng nhận mọi tốc độ khung, trình xem hay đường xuất. Bài phân tích này không chạy ứng dụng Capturia, bộ kiểm thử native hoặc trình xem GIF.
Vì vậy, một câu kỹ thuật chính xác là: “Tại phiên bản 8204e3e3, bộ xuất GIF của Capturia chuyển từ độ trễ cố định bị bỏ phần lẻ sang làm tròn tích lũy; với 30 khung mỗi giây, cách tính đã xem xét cho tổng một giây độ trễ khai báo trên ba mươi khung.” Câu đó xác định dự án, phiên bản, cơ chế và kết quả có giới hạn, mà không nhận quyền tác giả của toàn bộ ứng dụng hay bịa ra cải thiện tốc độ phát đã đo được.
Kết nối thông báo giấy phép với lời ghi nhận trong portfolio
Tệp LICENSE tại phiên bản cố định giữ các thông báo của OpenScreen bên cạnh thông báo của Capturia. Văn bản nói rõ thông báo được thêm vào không thay thế thông báo upstream. Điều kiện cấp phép MIT yêu cầu giữ thông báo bản quyền và thông báo cấp phép trong các bản sao hoặc phần đáng kể của phần mềm.
Lời ghi nhận trong portfolio không thay thế những thông báo đi cùng bản phân phối. Ngược lại, có tệp giấy phép không làm phần giới thiệu hàm ý một người tự tạo toàn bộ dự án trở nên chính xác. Chúng xử lý các nghĩa vụ liên quan nhưng khác nhau: giữ điều khoản gắn với phần mềm và truyền đạt ai đóng góp phần nào.
Thông báo bên thứ ba của kho mã cũng mô tả những thành phần có điều khoản riêng, gồm thư viện native, trọng số mô hình và phông chữ. Nhãn MIT ở cấp dự án không nên biến thành câu “mọi thành phần đi kèm đều có cùng giấy phép”. Hãy coi danh mục thông báo là tài liệu cần đối chiếu với một gói cụ thể, không phải bằng chứng rằng bài này đã kiểm tra nội dung gói ấy.
GitHub giải thích rằng cơ chế phát hiện giấy phép so sánh các tệp giấy phép trong kho với những giấy phép đã biết. Điều đó giúp tìm hiểu dự án. Nó không biến huy hiệu thành bản kê đầy đủ mọi sản phẩm nằm trong bộ cài.
Viết đoạn mà người đánh giá có thể lần theo
Thử bài tập với một thay đổi thật từ dự án đã ghi nhận nguồn gốc. Viết bốn câu: quan hệ với upstream; thay đổi cụ thể và phiên bản; bằng chứng về hành vi; giới hạn còn lại. Đặt liên kết trực tiếp cạnh nhận định mà nó hỗ trợ. Nếu kiểm thử mới được đề xuất, dùng cách diễn đạt ở tương lai. Nếu đã chạy, nêu đầu vào, kết quả mong đợi và phạm vi thực tế.
Với ví dụ GIF, đoạn bằng chứng có thể nói mã nguồn và kiểm thử được thêm vào đã được xem xét, còn phép tính cho 30 khung đã được tái hiện riêng. Một lần chạy xuất native sau này có thể bổ sung bản dựng chính xác, hệ điều hành, tệp tạo ra và hành vi trình xem. Nó mở rộng bằng chứng thay vì viết lại nguồn gốc của dự án nền.
Cuối cùng, bỏ các nhận định mơ hồ mà bằng chứng không gánh được. Giữ phần đóng góp còn lại. Ghi nhận rõ nguồn gốc giúp portfolio thể hiện bảo trì, gỡ lỗi, tích hợp và phán đoán kỹ thuật ở đúng quy mô, đồng thời dành sự ghi nhận dễ thấy cho những người tạo nên nền tảng.