Hướng dẫn sử dụng PR xếp chồng của Graphite trên GitHub

Nếu bạn chưa biết cách tận dụng Graphite nhưng đồng nghiệp của bạn đang ca ngợi nó, thì đây là những điều tôi ước mình được biết ngay từ đầu khi chúng tôi bắt đầu thử nghiệm với Graphite tại Semgrep. Tôi đề xuất một quy trình giúp dễ dàng sửa đổi các cam kết trước đó, giảm xung đột và tránh việc có những thay đổi không liên quan trong cùng một PR.

PR xếp chồng là gì?

Một xếp chồng pull requests không thực sự là một xếp chồng pull requests, mà nên được coi là một xếp chồng các thay đổi. Mặc dù về mặt kỹ thuật, mỗi thay đổi trong xếp chồng đều trở thành một pull request trên GitHub như chúng ta đã biết, nhưng một xếp chồng thay đổi về mặt chức năng tương đương với một pull request lớn truyền thống thực hiện một tính năng mới theo nhiều bước.

Cách hiểu một xếp chồng:

1. Một xếp chồng Graphite nên được xem như một chuỗi các thay đổi cần thiết để cung cấp một tính năng mới.
2. Mỗi thay đổi nên là một cam kết Git duy nhất mà sẽ được sửa đổi nhiều lần.

Quy trình đề xuất

Tạo một xếp chồng

Đầu tiên, hãy đặt nhánh hiện tại về nhánh chính của kho chứa của bạn như bạn đã làm trước khi tạo một nhánh dành cho pull request:

$ git checkout main

Sau đó, thực hiện các thay đổi cho mã của bạn cho đến khi nó có thể được hợp nhất hoặc cho đến khi bạn muốn sao lưu. Không sao nếu nó chưa hoàn thành.

Tiếp theo, hãy cam kết mã của bạn như là bộ thay đổi đầu tiên:

$ gt create

Các tùy chọn hữu ích bao gồm -a để thêm tất cả các tệp và -m để đặt thông điệp cam kết. Tên nhánh có thể được chỉ định như một đối số nếu bạn không thích tên mà Graphite đã gán.

Tiếp tục làm việc trên thay đổi cuối cùng

Giả sử bạn đã hoàn thành một ngày làm việc bằng cách cam kết một thay đổi với gt create. Ngày hôm sau, bạn sẽ tiếp tục công việc bằng cách thực hiện các sửa đổi cho đến khi bạn hài lòng với mã của mình. Bây giờ, thay vì thêm một cam kết mới, bạn sẽ sửa đổi cam kết cuối cùng bằng cách thêm các thay đổi mới của mình. Graphite cung cấp lệnh modify để làm điều này một cách thuận tiện:

$ gt modify -a

Đó là tất cả. Ý chính ở đây là chúng tôi giữ mỗi thay đổi có ý nghĩa như một cam kết Git mà có thể được sửa đổi sau này.

Thêm một thay đổi khác

Giả sử bạn cần thực hiện một thay đổi tạm thời khác trước khi hoàn thành tính năng của mình. Như trước, bạn sửa đổi mã của mình như thường lệ. Bạn sau đó cam kết nó như một cam kết Git. Cam kết này cũng sẽ được coi là một nhánh Git riêng biệt sau này có liên quan đến pull request của riêng nó. Lệnh, như trước, là gt create:

$ gt create -a -m 'Một thay đổi tạm thời khác'

Sử dụng gt rename để thay đổi tên nhánh Git nếu bạn muốn.

Chỉnh sửa một thay đổi trước đó

Tại thời điểm này, bạn có thể đã nhận ra rằng Graphite dựa vào việc chỉnh sửa lịch sử Git. Đây là những gì chúng tôi đang làm ở đây. Từ quan điểm của Git, một xếp chồng thay đổi là một nhánh của một nhánh của một nhánh... Từ quan điểm của Graphite, đó là một xếp chồng hoặc chuỗi các thay đổi mà có thể được xem xét và sửa đổi sau này theo bất kỳ thứ tự nào. Kiểm tra xếp chồng và vị trí của bạn trong xếp chồng với:

$ gt ls

Điều hướng trong xếp chồng, tức là thay đổi nhánh/cam kết git hiện tại với gt up và gt down cho đến khi nhánh hiện tại là nhánh tương ứng với thay đổi bạn muốn chỉnh sửa. Ví dụ, quay lại thay đổi trước với:

$ gt down

Bây giờ, chỉnh sửa mã của bạn và cam kết nó như đã mô tả trước đó, không bằng cách giới thiệu một cam kết mới, mà bằng cách sửa đổi cam kết:

$ gt modify -a

Với lệnh này, Graphite sẽ sửa đổi cam kết hiện tại và cập nhật các thay đổi tiếp theo bằng cách sử dụng git rebase bên trong.

Đẩy công việc lên để lưu

Như một biện pháp sao lưu, bạn nên đẩy mã của mình lên GitHub hoặc tương đương một cách thường xuyên. Bạn sẽ thực hiện điều này cho tất cả các thay đổi trong xếp chồng cùng một lúc với:

$ gt submit

Điều này sẽ tạo một pull request cho mỗi thay đổi trong xếp chồng, đưa bạn đến giao diện web của Graphite. Tuy nhiên, những pull request này không phải là quyết định cuối cùng. Nếu bạn chưa sẵn sàng để gửi chúng để xem xét, bạn có thể lưu chúng nhưng không nhấn nút Xuất bản hoặc bạn có thể xuất bản chúng nhưng đánh dấu một số là bản nháp. Có các nút cho những điều này. Tính năng bản nháp giống như tính năng bản nháp của GitHub.

Xem xét và hợp nhất xếp chồng

Một xếp chồng thay đổi chuyển sang một chuỗi các pull request có thể được xem xét từ ứng dụng Web của Graphite hoặc trên GitHub. Trên GitHub, có một kiểm tra CI ngăn cản người xem xét hợp nhất một PR nếu các PR phụ thuộc tương ứng với những thay đổi trong xếp chồng chưa được hợp nhất.

Đồng bộ hóa với nhánh chính

Để nhập các thay đổi mới nhất của nhánh chính vào xếp chồng của bạn, sử dụng:

$ gt sync

Điều này tương đương với một Git rebase cho mỗi thay đổi của bạn. Bạn sẽ phải giải quyết xung đột theo cách thông thường, bằng cách làm theo hướng dẫn. Đây là lúc có một cam kết duy nhất cho mỗi thay đổi hợp lý trong xếp chồng sẽ hữu ích.

Thực hiện các thao tác Git khác

Bạn vẫn có thể sử dụng các lệnh Git thông thường nhưng một số lệnh đã bị ngưng khi làm việc trên một xếp chồng Graphite. git commit có thể ổn nhưng không cần thiết vì bạn thường sử dụng gt create hoặc gt modify thay thế. git push có thể cũng ổn nhưng gt submit sẽ đẩy tất cả các nhánh tương ứng với xếp chồng của bạn cùng một lúc. Việc viết lại lịch sử với git rebase có thể tốt nhất là nên tránh nếu bạn đang làm việc trên một xếp chồng Graphite. git merge và git pull cũng nên được tránh vì gt sync sẽ xử lý đồng bộ hóa và giải quyết xung đột cho toàn bộ xếp chồng.

Các thao tác chỉ đọc như git log tất nhiên là ổn và được khuyến nghị trong các tình huống tương tự như với quy trình làm việc truyền thống của Git/GitHub.

Dọn dẹp

Graphite sẽ tự động đề nghị xóa các nhánh đã được hợp nhất (không giống như Git khi hợp nhất một nhánh trên GitHub với squash-and-merge).

Những điều quan trọng cần ghi nhớ

1. Đừng lo lắng về việc lập kế hoạch công việc của bạn trước. Bạn không cần phải làm điều đó. Hãy tiếp tục chỉnh sửa mã của bạn bằng cách sửa đổi cam kết cuối cùng với gt modify cho đến khi mã của bạn hoạt động và bạn cảm thấy thoải mái để chuyển sang một thứ khác... đó sẽ là một thay đổi mới trong xếp chồng. Bạn luôn có thể quay lại và chỉnh sửa các thay đổi trước đó trong xếp chồng sau này.
2. Hãy chấp nhận việc chỉnh sửa lịch sử Git. gt ls/gt up/gt down/gt modify sẽ làm điều đó cho bạn.
3. Giảm thiểu số lượng cam kết để dễ dàng giải quyết xung đột. Điều này đạt được bằng quy trình đề xuất ở trên, nơi bạn mở rộng các cam kết trước đó.

Những lợi ích mà bạn sẽ nhận được từ cách tiếp cận này là:

• Dễ dàng giải quyết xung đột do có ít cam kết hơn
• Dễ dàng xem xét mã do có một pull request cho mỗi thay đổi có ý nghĩa

Các câu hỏi mở

Xem xét nhiều thay đổi riêng biệt nhưng hợp nhất chúng như một?

Các kiểm tra CI sẽ cần phải vượt qua cho mỗi thay đổi/cam kết/PR trong xếp chồng. Thường thì, điều này có ý nghĩa cho hai thay đổi được xem xét riêng biệt ngay cả khi chúng cần lẫn nhau để phần mềm hoạt động. Vì việc chỉ hợp nhất một trong những cam kết này sẽ làm hỏng xây dựng và thất bại kiểm tra CI, có cách nào để gửi hai thay đổi này để xem xét riêng biệt nhưng yêu cầu chúng được hợp nhất như một không?

Tại sao lại gọi là một xếp chồng?

Trong khoa học máy tính, một xếp chồng hoặc container LIFO (last-in-first-out) là một tập hợp các phần tử mà chỉ phần tử được thêm gần đây nhất có thể được truy cập. Điều này không hoàn toàn giống với ý nghĩa được sử dụng bởi Graphite, điều này có thể gây nhầm lẫn cho một số người trong chúng ta. Ngay cả với những người yêu bánh pancake bình thường, khái niệm về một xếp chồng ngụ ý rằng việc sửa đổi các phần tử bên trong xếp chồng là khó khăn và không bình thường. Graphite làm cho việc sửa đổi các mục trong xếp chồng trở nên dễ dàng và thú vị, khiến nó cảm thấy ít giống như một xếp chồng hơn.

Thông báo

Tôi vẫn còn mới trong lĩnh vực này. Mong bạn thông cảm cho một số sai sót và thiếu sót.