From 8d5445631c474779b1a0ee37171d49ba01d8066f Mon Sep 17 00:00:00 2001 From: Alexander Kriegisch Date: Sat, 17 Feb 2024 12:50:55 +0700 Subject: [PATCH] Rephrase "check the diffs before committing" section Signed-off-by: Alexander Kriegisch --- docs/developer/RELEASE.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/developer/RELEASE.md b/docs/developer/RELEASE.md index 991cd4b69..69db8a0f5 100644 --- a/docs/developer/RELEASE.md +++ b/docs/developer/RELEASE.md @@ -192,13 +192,17 @@ folder `doc/latest` in the website repository or maybe to a folder named after t the future. Presently, we only publish the latest documentation, always overwriting the preceding version. The entry page for the generated docs is published [here](https://eclipse.dev/aspectj/doc/latest/index.html). -Make sure to check the diffs before committing. If a certain part of the documentation (e.g. developer's notebook, -programming guide) has not changed HTML-wise, you also do not need to commit the corresponding PDF, even though it -might be binarily different. But if the HTML content is unchanged, the PDF should look the same as before, too, unless -you have reason to believe otherwise (e.g. changes in style in the generator options). Inspecting the diffs, you also -want to identify other generic changes, such as timestamps, years in copyright notices etc. It is an ongoing process -to optimise such changes away to achieve stable docs and small commit diffs. If you spot something, make sure to -optimise the build process accordingly. +Make sure to **check the diffs** before committing: + * If a certain part of the documentation (e.g. developer's notebook, programming guide) has not changed HTML-wise, + you also do not need to commit the corresponding PDF, even though it might be binarily different. But if the HTML + content is unchanged, the PDF should look the same as before, too, unless you have reason to believe otherwise + (e.g. changes in style in the generator options). + * Depending on your local OS and Git configuration, some changes might only be caused by different line delimiters, + i.e. CRLF on Windows and LF on Linux and MacOS. Please avoid committing those, changing the files back and forth. + Rather run dos2unix or unix2dos on those files to eliminate unnecessary and possibly huge diffs. + * You also want to identify other generic changes, such as timestamps, years in copyright notices etc. It is an + ongoing process to optimise such changes away to achieve stable docs and small commit diffs. If you spot + something, make sure to improve the build process accordingly. After pushing changes to the website repository, they should be published by a batch process automatically after a short delay (usually a few minutes). -- 2.39.5