Documentation for merge trains

channable / hoff

A gatekeeper for your commits

Apache License 2.0

41 stars 3 forks source link

Documentation for merge trains #179

Closed rudymatela closed 2 years ago

rudymatela commented 2 years ago

Closes: #169

This PR documents current behaviour with regards to merge trains:

readme.md

TODO

[x] add mention of merge trains on the readme file;
[x] add happy-day diagram without merge trains
[x] add happy-day diagram with merge trains
[x] diagram for when build fails
[x] diagram for when rebase fails
[x] different icon for cancelling a build :no_entry_sign:
[x] describe each case textually
[x] diagram for delayed build statuses ("wrong" order)
[x] document when PR is closed (same as when build fails)
[x] document when new commit arrives in the train (same as when build fails)
[x] add screenshots
[x] go around the code adding assorted comments

rudymatela commented 2 years ago

History was quite messy up to this point. So I squashed my changes now.

rudymatela commented 2 years ago

@fatho and @ReinierMaas, in this PR I try to document the behaviour of merge trains well so that:

in case something strange happens on a sequence of PRs, we can double-check with the docs if it is expected behaviour. Sometimes what is the correct course of action is unintuitive. (Builds restarted seemingly out of nothing, but actually because the base branch has failed.);
to make it easier to understand the code.

I also slightly improved inline (Haddock) code documentation.

Please let me know your thoughts or if you have any suggestions.

rudymatela commented 2 years ago

... when reviewing the readme.md I recommend looking at the "rich diff".

rudymatela commented 2 years ago

@ReinierMaas Thanks for the review.

I believe to have addressed your comments in 465bb923c2b5e7696e22947d4cee9cefd55ae6a7, 91d8eac9db7fc51375e1609e69745e110eaf224e and 1724c9c6d0170032028fca897b768022b5485332. Can you please take a look again?

rudymatela commented 2 years ago

Almost done. Two more nits

:runner: Fixed! :smile:

rudymatela commented 2 years ago

I will merge now so I can prepare a release and deployment for tomorrow early morning. (The two nits were fixed :grin: If you have further comments let me know and I can try to address them in further PRs.)

@OpsBotPrime merge

OpsBotPrime commented 2 years ago

Pull request approved for merge by @rudymatela, rebasing now.

OpsBotPrime commented 2 years ago

Rebased as e0cd286121a38e89561e0dfc732ac6de4bb73d9b, waiting for CI …

OpsBotPrime commented 2 years ago

CI job :yellow_circle: started.