Lịch sử cam kết có nên được sử dụng để truyền đạt thông tin quan trọng cho các nhà phát triển?

Trong cuộc họp liên quan đến việc khôi phục SDK của bên thứ ba từ phiên bản mới nhất, lưu ý rằng các nhà phát triển của chúng tôi đã gắn cờ trong lịch sử cam kết rằng phiên bản mới nhất không nên được sử dụng.

Một số nhà phát triển lập luận rằng đây là một thực tiễn tồi và thay vào đó nó nên được ghi chú trong tệp nguồn (tức là // Don't upgrade SDK Version x.y.z, see ticket 1234) hoặc trong READMEtệp cấp dự án . Những người khác lập luận rằng vì lịch sử cam kết là một phần của tài liệu dự án, đây là một vị trí có thể chấp nhận được đối với thông tin đó vì tất cả chúng ta nên đọc nó.

Lịch sử cam kết có nên được sử dụng để truyền đạt thông tin quan trọng cho các nhà phát triển khác hay thông tin đó nên được sao chép sang một vị trí khác như dự án READMEhoặc nhận xét trong tệp nguồn có liên quan?

Nếu tôi định xem xét nâng cấp lên phiên bản mới hơn của SDK bên thứ ba, thì nơi cuối cùng tôi sẽ tìm thấy là trong lịch sử của hệ thống kiểm soát nguồn.

Nếu sản phẩm của bạn đang sử dụng phiên bản 2.0 của SDK và ai đó quan tâm đến việc nâng cấp lên 3.0, tôi không nghĩ rằng hợp lý khi nghĩ rằng họ nên nhìn ngược thời gian trong hệ thống kiểm soát nguồn của bạn để biết rằng đó không phải là một ý tưởng hay.

Ở đây, chúng tôi có một wiki nhóm có rất nhiều trang với thông tin thú vị mà mọi nhà phát triển đều đọc (quy ước mã hóa, cách thiết lập môi trường phát triển để xây dựng sản phẩm, thứ gì bên thứ ba bạn cần cài đặt, v.v.). Đây là nơi thích hợp để cảnh báo chống lại việc nâng cấp thư viện của bên thứ ba.

Cần lưu ý trong lịch sử cam kết nhưng nơi tốt nhất tuyệt đối để đặt thông báo là ở cùng nơi bạn xác định sự phụ thuộc. Ví dụ: nếu bạn có tệp maven .pom khai báo các phụ thuộc giả của bạn, tôi sẽ làm như sau:

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

Trực tiếp trên <dependency>dòng của bạn .

Vấn đề # 123 sẽ bao gồm các chi tiết về cách nó gặp sự cố, phiên bản bạn đã cập nhật gây ra sự cố và sau đó có thể sẽ được thêm vào hồ sơ tồn đọng của bạn để xem lại sau - có thể phiên bản mới hơn sẽ khắc phục sự cố. Tự động bằng cách chỉnh sửa vé hoặc tự thủ công, nó sẽ gửi email cho nhóm để cho họ biết về vấn đề hiện tại và bằng cách ở trong trình theo dõi, nó cho phép mọi người tìm lại sau.

Lý do để đưa nó vào tuyên bố phụ thuộc là bởi vì bất cứ ai muốn thay đổi phiên bản sẽ thấy nó tại thời điểm họ muốn thay đổi nó và hiểu lý do tại sao họ không nên.

Tôi sẽ không bình luận trong mã nguồn bởi vì tôi có thể dễ dàng hình dung ra tình huống ai đó chạy kiểm tra các phụ thuộc của bạn và bắt đầu nâng cấp chúng. Họ không cần phải quét mã cơ sở cho mọi bình luận TODO để làm điều đó.

Liên kết với vé vấn đề cho phép một nhà phát triển tò mò biết làm thế nào nó thất bại và có khả năng xem lại nó sau này. Không có điều đó, nó có thể trở nên khá tĩnh và không bao giờ được cập nhật lại.

Các mẩu thông tin quan trọng và không trực quan nên được ghi lại nơi mọi người sẽ tìm kiếm khi xem xét thông tin.

Đối với các nhóm và dự án tôi đã làm việc, tôi sẽ cam kết quay lại với nhận xét về lý do tại sao phiên bản mới thất bại. Tôi sẽ thêm một câu chuyện tồn đọng để thử lại bản nâng cấp nếu phiên bản mới được sửa. Tôi sẽ thêm ý kiến ​​vào hệ thống xây dựng / tập lệnh xây dựng nơi thư viện được liên kết.

Việc khôi phục sẽ cung cấp cho các nhà phát triển trong tương lai bối cảnh khi nhìn vào lịch sử của dự án. Câu chuyện tồn đọng giữ cho nhu cầu nâng cấp này là một phần tích cực của dự án. Các ý kiến ​​hệ thống xây dựng là đúng nơi các thay đổi sẽ cần phải có khi thư viện cuối cùng được cập nhật.

Tôi sẽ không bình luận nó trong mã và tôi sẽ không thêm nó vào README. Các nhà phát triển suy nghĩ về việc thử nâng cấp sẽ không nhìn vào những mảnh này. Nếu bạn thêm nó vào đó, thì khi vấn đề với thư viện cuối cùng đã được khắc phục và việc nâng cấp được thực hiện, bạn sẽ cần phải xóa nó. Bước này thường bị lãng quên: dẫn đến các ghi chú phản tác dụng với dự án.

Nếu dự án của bạn có một thiết lập khác hoặc một luồng khác, thì câu trả lời của bạn có thể khác. Tôi nghĩ chìa khóa là đưa thông tin đúng là nhà phát triển sẽ nhìn thấy nó khi thực hiện công việc nâng cấp. Theo cách đó, nếu thời gian không phù hợp để nâng cấp, nhà phát triển sẽ thấy nó và dừng lại, và khi đến lúc, nhà phát triển sẽ nhìn thấy nó và xóa ghi chú để nó không gây nhầm lẫn cho các nhà phát triển trong tương lai.

Tôi muốn làm cho bình luận của Matthew chú ý hơn bằng cách nêu bật ý tưởng quan trọng của anh ấy trong một câu trả lời. Có một lý do tại sao bạn không muốn nâng cấp SDK của mình và lý do đó nên được ghi lại trong một bài kiểm tra đơn vị. Không phải là kiểm tra số sửa đổi, mà là lý do cơ bản thực tế.

Ví dụ: giả sử có một lỗi trong phiên bản mới. Viết một bài kiểm tra đơn vị kiểm tra lỗi đó. Nếu sau đó họ sửa lỗi đó trong SDK, thì việc nâng cấp sẽ diễn ra suôn sẻ. Nếu có thay đổi API không tương thích, hãy viết một bài kiểm tra để kiểm tra xem mã của bạn có hỗ trợ API mới hay SDK hỗ trợ API cũ hay không. Đó là một bài kiểm tra tích hợp nhiều hơn một bài kiểm tra đơn vị, nhưng vẫn có thể thực hiện được.

Công ty của tôi tạo ra hơn 50 cam kết mỗi ngày và chúng tôi không thực sự lớn. Ngay cả khi mọi nhà phát triển đọc mọi thông điệp cam kết, điều mà chúng ta không thể nói, toàn bộ lý do chúng ta cần một lịch sử cam kết được ghi lại là vì mọi người không thể nhớ nó. Và mọi người không quay lại và đọc lịch sử sau đó trừ khi có vấn đề. Và họ không có lý do để nghi ngờ một vấn đề về nâng cấp mà theo như họ biết chưa xảy ra.

Bằng mọi cách, hãy gửi email để ngăn chặn việc sao chép công việc trong thời gian tới và lưu ý nó trong tập lệnh xây dựng của bạn và README hoặc errata. Tuy nhiên, đặc biệt nếu vấn đề với phiên bản mới là tinh tế và tốn thời gian để khắc phục sự cố, bạn cần một cách để làm cho nó rõ ràng. Điều đó có nghĩa là một bài kiểm tra đơn vị.

Tôi đang đặt lại câu hỏi là "Tôi có nên truyền đạt thông tin quan trọng mà tôi phát hiện ra cho các thành viên còn lại trong nhóm chỉ qua tin nhắn cam kết không?" Bởi vì tôi nghĩ điều đó rõ ràng là không, bạn không nên. Tôi cố gắng giao tiếp nhiều (đây là điều mà hầu hết các nhóm phát triển, theo kinh nghiệm của tôi, cần nỗ lực tích cực) và tôi chắc chắn làm mọi thứ có thể để tránh tạo ra cạm bẫy hoặc để họ nói dối.

Nếu chuỗi hành động dẫn tôi đến một khám phá như vậy được kích hoạt bởi một vé, tôi sẽ cập nhật vé (và đảm bảo rằng những người nên biết điều này có thể nhìn thấy), có lẽ tôi sẽ đề cập trực tiếp (hy vọng ít nhất là để lại cho ai đó một cảm giác cằn nhằn rằng "Gee, tôi nghĩ Damon đã nói gì đó về việc cập nhật điều đó"), và tất nhiên tôi sẽ để lại một bình luận trong mã tại thời điểm SDK được đưa vào để không ai có thể cập nhật nó mà không có cơ hội nhìn thấy nó Tôi có thể thấy nếu tôi có thể kẹt nó ở một nơi nào đó trên wiki dev của chúng tôi, mặc dù điều đó được thực hiện nhiều hơn với mục đích hướng tới những người tuyển dụng trong tương lai, chứ không phải nhóm hiện tại.

Chỉ mất vài phút so với thời gian có thể gặp phải và khám phá vấn đề. Tôi chắc chắn sẽ không quyết định rằng một trong những phần ít được sử dụng nhất, tín hiệu thấp của tài liệu của chúng tôi và để nó ở đó.

Nó nên có trong lịch sử cam kết nhưng nó không chỉ nên trong lịch sử cam kết, hãy tưởng tượng trong một khoảnh khắc bạn thuê một nhà phát triển mới. Bạn có mong đợi rằng nhà phát triển mới sẽ đọc mọi thông điệp cam kết trong 10 năm qua của dự án của bạn bởi vì một vài trong số họ sẽ rất quan trọng để hiểu cơ sở mã của bạn?

Thứ hai nói tình huống nhưng không thay đổi mã, bạn sẽ thực hiện "tài liệu" cam kết để bạn có thể thêm thông báo cam kết dọc theo dòng "thông báo cam kết từ phiên bản 5432 hiện không chính xác, đây là tình huống hiện tại."

Tôi không chắc nhóm của bạn giao tiếp như thế nào nhưng tôi tin rằng cách hiệu quả nhất để nói điều này là trước tiên gửi và gửi email cho nhóm email của nhóm, được đánh dấu là "KHẨN"

Các bạn, chúng ta không thể sử dụng SDK v xyz vì nó khiến bộ đệm Foo bị tràn và dịch vụ Bar sẽ bị sập. Gắn bó với phiên bản xyy

Đó là những gì chúng tôi đã làm ở đây và đó là cách đáng tin cậy nhất để đưa thông điệp ra khỏi đó. Nếu bạn thực sự muốn cầu kỳ (và nếu hệ thống email của bạn cho phép), hãy yêu cầu "đọc biên nhận" trên email.

Khi bạn đã nói với cả nhóm, tài liệu chi tiết hơn sẽ được đưa vào wiki nhóm. Điều này sẽ thay đổi, tùy thuộc vào cách bạn cấu trúc tài liệu của bạn. Nếu bạn có một phần dành riêng cho các ứng dụng của mình Phụ thuộc và Yêu cầu, đó sẽ là một nơi tốt để thêm nó.

Một vị trí bổ sung để ghi lại loại vấn đề này có thể nằm trong chính mã nguồn, mặc dù điều đó có thể không phải lúc nào cũng hoạt động. Nếu SDK version ...chỉ được tham chiếu ở một hoặc hai nơi rõ ràng, bạn có thể bao gồm một lưu ý về việc không nâng cấp.

Lịch sử tệp trong kiểm soát nguồn có thể rất dài và tùy thuộc vào các nhà phát triển, có thể có một vài mục mỗi ngày. Một người nào đó được nghỉ hè một tuần có thể không có thời gian để đọc lịch sử cam kết của một tuần. Tệp README là một nơi tốt hơn vì nó tập trung hơn một chút và mọi người có thể có xu hướng đọc nó nhiều hơn, nhưng bạn không thể đảm bảo rằng mọi người sẽ thực sự đọc README. Chà, tôi cho rằng họ có thể nếu họ thấy nó đã bị thay đổi ...

Một cái gì đó như thế này nên được đưa vào các bình luận cam kết, nhưng nó cũng sẽ được hưởng lợi từ việc ở những nơi khác.

Bất cứ ai đưa ra quyết định nâng cấp, cần phải có sự thật. Người đó có thể không sống trong kiểm soát nguồn. Điều gì xảy ra nếu ai đó đã đọc về vấn đề này trên SO và không bao giờ đặt nó vào cơ sở mã?

Cần phải có một số loại tài liệu về SDK của bên thứ ba này.

• vấn đề gì nó giải quyết?
• Tại sao cái này đặc biệt được chọn?
• Những điều cần cân nhắc cần được thực hiện cho đến tận: phiên bản, nâng cấp, thử nghiệm, v.v.
• Ai đưa ra quyết định này?

Bạn có một trường hợp khi một cái gì đó như thế này được đưa vào kiểm soát phiên bản và bạn nên khuyên mọi người sử dụng thông tin này càng nhiều càng tốt. Chỉ nhóm của bạn mới có thể quyết định nơi ai đó sẽ thực hiện tìm kiếm trong bất kỳ tài liệu, kiểm soát nguồn hoặc theo dõi lỗi nào để có được càng nhiều thông tin càng tốt về chủ đề này. Nếu không, bạn sẽ quên, dù sao đi nữa, ai đó sẽ làm điều đó và bạn sẽ may mắn nếu nó chạy bộ nhớ của ai đó và nhanh chóng quay trở lại.

Lịch sử là một nơi tuyệt vời để đặt dữ liệu dành cho người đọc đang có ý thức tìm kiếm nó và có ý thức chung về nơi cần có. Đó là một nơi rất tồi tệ để đặt dữ liệu phải được trao cho người dùng, thay vì tìm kiếm.

Lịch sử là các cơ quan rất lớn của văn bản tương đối chưa được sắp xếp. Họ thường có ý định cung cấp cho nhà phát triển thông tin chi tiết về những gì đã thay đổi và lý do tại sao nó được thay đổi. Đây có thể là quá tải thông tin trừ khi người ta biết những gì họ đang tìm kiếm.

Nếu người dùng không biết những gì họ đang tìm kiếm, thì thông tin sẽ nhanh chóng bị chôn vùi dưới hàng trăm nhật ký cam kết và họ không có công cụ nào để cắt xén đống thông tin trước mặt họ.

Tôi giải thích tình huống này là có hai vấn đề cơ bản, có thể là ba.

• Một bản nâng cấp SDK không mong muốn đã đưa nó vào nguồn, nơi nó có thể ảnh hưởng tiêu cực đến sản phẩm.
• Từ câu hỏi: người đóng góp thực hiện nâng cấp không mong muốn không biết về quyết định cụ thể trước đây không nâng cấp.

Theo tôi, điều đầu tiên là nghiêm trọng nhất. Nếu một bản nâng cấp SDK không mong muốn có thể biến nó thành mã, thì các vấn đề khác cũng có thể xảy ra.

Ai đó đề nghị thêm một trường hợp thử nghiệm đơn vị sẽ thất bại nếu phát hiện nâng cấp. Mặc dù nó sẽ ngăn việc nâng cấp xảy ra, tôi tin rằng đây là một con đường nguy hiểm, dẫn đến dòng dung nham theo thời gian. Dường như không thể tránh khỏi một lúc nào đó trong tương lai SDK sẽ được nâng cấp, để mang lại các tính năng hoặc sửa lỗi mới hoặc do phiên bản cũ không còn được hỗ trợ. Hãy tưởng tượng việc gãi đầu, thậm chí có thể xảy ra tranh luận, điều đó sẽ xảy ra khi một bài kiểm tra đơn vị như vậy sau đó thất bại.

Tôi nghĩ giải pháp chung nhất là điều chỉnh quá trình phát triển. Đối với git, sử dụng quá trình yêu cầu kéo . Đối với Subversion và các công cụ cũ hơn, sử dụng các nhánh và diff. Nhưng có một số quy trình cho phép các nhà phát triển cao cấp nắm bắt các loại vấn đề này trước khi họ đưa nó vào cơ sở mã và ảnh hưởng đến các nhà phát triển khác.

Nếu quy trình yêu cầu kéo đã được sử dụng trong tình huống của bạn và nếu mỗi yêu cầu kéo hẹp và cụ thể, sẽ không lãng phí nhiều thời gian. Yêu cầu kéo để nâng cấp SDK sẽ được gửi và từ chối với nhận xét rằng không muốn nâng cấp. Không ai khác sẽ bị ảnh hưởng, và bây giờ sẽ không cần phải hoàn nguyên nâng cấp SDK.

Nhưng để trả lời trực tiếp câu hỏi ban đầu, tôi đồng ý với những người khác hy vọng tất cả các nhà phát triển sẽ đọc đầy đủ toàn bộ lịch sử sửa đổi của mã, ghi chú phát hành, v.v. vì những thông báo như thế này là lãng phí thời gian quý giá. Có gì sai với một e-mail nhóm ngắn?

Vấn đề thứ ba có thể xảy ra: Tại sao nâng cấp không muốn ở nơi đầu tiên? Rõ ràng ít nhất một nhà phát triển nghĩ rằng việc nâng cấp sẽ là một điều tốt. Có nhiều lý do tốt để trì hoãn nâng cấp, nhưng cũng có nhiều lý do xấu. Cẩn thận để tránh dòng dung nham (mã tương thích ngược không cần thiết) và sùng bái hàng hóa ("chúng tôi không thể nâng cấp điều đó, nhưng tôi không biết tại sao")

Tôi có thể nói rằng việc thêm loại thông tin đó vào lịch sử cam kết là ổn nhưng nó vẫn cần phải được ghi lại đúng cách. Gần đây chúng tôi đã bắt đầu sử dụng hợp lưu (bởi atlassian). Có thể tìm kiếm, bạn có thể đặt một số trang nhất định làm mục yêu thích, v.v.

Một số công cụ khác có thể là một sổ ghi chép công khai trong tài liệu evernote hoặc google.

Mở rộng câu trả lời của Karl , tôi sẽ thực hiện một cách tiếp cận tự động thực thi các hạn chế như là một phần của quy trình đăng ký. Bạn cần một cái gì đó không yêu cầu bất kỳ hành động chủ động nào thay mặt cho nhà phát triển, chẳng hạn như đọc tài liệu / wiki / README và không thể bị ghi đè một cách bí mật.

Trong vùng đất kiểm soát nguồn TFS, bạn có thể mã hóa các chính sách đăng ký tùy chỉnh thực thi các quy tắc khi đăng ký. Ví dụ: bạn có thể xác định chính sách đánh giá phiên bản trong tệp cấu hình với đăng ký đang chờ xử lý và sẽ thất bại nếu không bằng xyz Các quy tắc này thực sự ngăn nhà phát triển thực hiện đăng ký và có thể cung cấp thông báo mô tả. Các chính sách có thể bị ghi đè, nhưng có thể tạo cảnh báo khi điều này xảy ra.

Một giải pháp thay thế có thể được kiểm tra - kiểm tra không thành công với một số hình thức kiểm tra đơn vị đánh giá trực tiếp hoặc gián tiếp phiên bản SDK, như Karl đã đề cập.

Tôi đánh giá cao câu trả lời này rất trung tâm TFS, nhưng có thể các tính năng tương tự tồn tại trong các hệ thống kiểm soát / CI phiên bản áp dụng trong tình huống của bạn (nếu không phải là TFS).