Patrick Georgi has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Documentation: Encourage documentation with code changes
The resource allocator woes post-4.12 release showed room for improvement on both discussion and documentation. To encourage this (and encourage reviewers to look out for issues in that space), extend the review guidelines so that they encourage to more clearly document the reason for a change with the change (commit message or our documentation) and also to loop in the mailing list.
Change-Id: I1962dba3fe7e1a01fa4c8b0058297c7d050cb7b7 Signed-off-by: Patrick Georgi pgeorgi@google.com --- M Documentation/getting_started/gerrit_guidelines.md 1 file changed, 17 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/93/41493/1
diff --git a/Documentation/getting_started/gerrit_guidelines.md b/Documentation/getting_started/gerrit_guidelines.md index 735ba3b..7b0c247 100644 --- a/Documentation/getting_started/gerrit_guidelines.md +++ b/Documentation/getting_started/gerrit_guidelines.md @@ -254,6 +254,23 @@ The script 'util/gitconfig/rebase.sh' can be used to help automate this. Other tags such as 'Commit-Queue' can simply be removed.
+* Check if there's documentation that needs to be updated to remain current +after your change. If there's no documentation for the part of coreboot +you're working on, consider adding some. + +* When contributing a significant change to core parts of the code base (such +as the boot state machine or the resource allocator), or when introducing a +new way of doing something that you think is worthwhile to apply across the +tree (e.g. board variants), please bring up your design on the mailing list +(coreboot@coreboot.org). When changing behavior substantially, an explanation +of what changes and why may be useful to have, either in the commit message +or, if the discussion of the subject matter needs way more space, in the +documentation. Since "what we did in the past and why it isn't appropriate +anymore" isn't the most useful reading several years down the road, such +a description could be put into the release notes for the next version +(that you can find in Documentation/releases/) where it will inform people +now without cluttering up the regular documentation, and also gives a nice +shout-out to your contribution by the next release.
Expectations contributors should have -------------------------------------
Angel Pons has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Patch Set 1: Code-Review+1
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Patch Set 1: Code-Review+1
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Patch Set 1:
(1 comment)
https://review.coreboot.org/c/coreboot/+/41493/1/Documentation/getting_start... File Documentation/getting_started/gerrit_guidelines.md:
https://review.coreboot.org/c/coreboot/+/41493/1/Documentation/getting_start... PS1, Line 264: mailing list : (coreboot@coreboot.org) Link to `Documentation/community/forums.md` instead?
Hello build bot (Jenkins), Paul Menzel, Angel Pons,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/41493
to look at the new patch set (#2).
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Documentation: Encourage documentation with code changes
The resource allocator woes post-4.12 release showed room for improvement on both discussion and documentation. To encourage this (and encourage reviewers to look out for issues in that space), extend the review guidelines so that they encourage to more clearly document the reason for a change with the change (commit message or our documentation) and also to loop in the mailing list.
Change-Id: I1962dba3fe7e1a01fa4c8b0058297c7d050cb7b7 Signed-off-by: Patrick Georgi pgeorgi@google.com --- M Documentation/getting_started/gerrit_guidelines.md 1 file changed, 17 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/93/41493/2
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Patch Set 2:
(1 comment)
https://review.coreboot.org/c/coreboot/+/41493/1/Documentation/getting_start... File Documentation/getting_started/gerrit_guidelines.md:
https://review.coreboot.org/c/coreboot/+/41493/1/Documentation/getting_start... PS1, Line 264: mailing list : (coreboot@coreboot.org)
Link to `Documentation/community/forums. […]
good point, done.
Angel Pons has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Patch Set 2: Code-Review+1
Was this change posted on the ML?
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Patch Set 2:
Patch Set 2: Code-Review+1
Was this change posted on the ML?
https://mail.coreboot.org/hyperkitty/list/coreboot@coreboot.org/thread/NX5MM...
Arthur Heymans has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Patch Set 2: Code-Review+2
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Patch Set 2: Code-Review+1
Patrick Georgi has submitted this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Documentation: Encourage documentation with code changes
The resource allocator woes post-4.12 release showed room for improvement on both discussion and documentation. To encourage this (and encourage reviewers to look out for issues in that space), extend the review guidelines so that they encourage to more clearly document the reason for a change with the change (commit message or our documentation) and also to loop in the mailing list.
Change-Id: I1962dba3fe7e1a01fa4c8b0058297c7d050cb7b7 Signed-off-by: Patrick Georgi pgeorgi@google.com Reviewed-on: https://review.coreboot.org/c/coreboot/+/41493 Tested-by: build bot (Jenkins) no-reply@coreboot.org Reviewed-by: Angel Pons th3fanbus@gmail.com Reviewed-by: Arthur Heymans arthur@aheymans.xyz Reviewed-by: Paul Menzel paulepanter@users.sourceforge.net --- M Documentation/getting_started/gerrit_guidelines.md 1 file changed, 17 insertions(+), 0 deletions(-)
Approvals: build bot (Jenkins): Verified Paul Menzel: Looks good to me, but someone else must approve Arthur Heymans: Looks good to me, approved Angel Pons: Looks good to me, but someone else must approve
diff --git a/Documentation/getting_started/gerrit_guidelines.md b/Documentation/getting_started/gerrit_guidelines.md index 735ba3b..59f675a 100644 --- a/Documentation/getting_started/gerrit_guidelines.md +++ b/Documentation/getting_started/gerrit_guidelines.md @@ -254,6 +254,23 @@ The script 'util/gitconfig/rebase.sh' can be used to help automate this. Other tags such as 'Commit-Queue' can simply be removed.
+* Check if there's documentation that needs to be updated to remain current +after your change. If there's no documentation for the part of coreboot +you're working on, consider adding some. + +* When contributing a significant change to core parts of the code base (such +as the boot state machine or the resource allocator), or when introducing +a new way of doing something that you think is worthwhile to apply across +the tree (e.g. board variants), please bring up your design on the [mailing +list](../community/forums.md). When changing behavior substantially, an +explanation of what changes and why may be useful to have, either in the +commit message or, if the discussion of the subject matter needs way more +space, in the documentation. Since "what we did in the past and why it isn't +appropriate anymore" isn't the most useful reading several years down the road, +such a description could be put into the release notes for the next version +(that you can find in Documentation/releases/) where it will inform people +now without cluttering up the regular documentation, and also gives a nice +shout-out to your contribution by the next release.
Expectations contributors should have -------------------------------------
9elements QA has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41493 )
Change subject: Documentation: Encourage documentation with code changes ......................................................................
Patch Set 3:
Automatic boot test returned (PASS/FAIL/TOTAL): 4/0/4 Emulation targets: "QEMU x86 q35/ich9" using payload TianoCore : SUCCESS : https://lava.9esec.io/r/3622 "QEMU x86 q35/ich9" using payload SeaBIOS : SUCCESS : https://lava.9esec.io/r/3621 "QEMU x86 i440fx/piix4" using payload SeaBIOS : SUCCESS : https://lava.9esec.io/r/3620 "QEMU AArch64" using payload LinuxBoot_u-root_kexec : SUCCESS : https://lava.9esec.io/r/3619
Please note: This test is under development and might not be accurate at all!