PP-1255: PBS Pro design document guidelines

#1

This post is to inform the development community of a new draft document available for review. The new document will serve as a set of guidelines to assist authors while composing design documents for PBS Pro. The draft document is available here: https://pbspro.atlassian.net/wiki/spaces/PD/pages/295567363/PP-1255%3A+Guidelines+for+design+documents

Please provide comments in response to this post. Once the review is complete, the document will be added to the PBS Pro developer guide pages.

Thanks in advance!

#2

“Don’t:
Document log messages unless required for QA and testing”

The above implicitly requires that ALL log messages that would be used to by QA or by PTL tests needs to be documented.

I think this is unnecessary, and is even a severe overhead. We do not document internal interfaces in the design document. Code and tests will anyway be updated by the Pull request before they can be merged in.

I suggest we modify that statement to say something like:

“Don’t:
Document log messages unless explicitly needed to be added to end user documentation”

#3

I agree with @subhasisb

#4

I also agree with Subhasis. Log messages are more for support and debugging and don’t really count as “design changes” in my mind. Accounting logs are kind of special as they are a supported interface to obtain accounting/statistical information, so if there’s a change in accounting logs, that does need to be documented, but all other log messages don’t really need to.

#5

I second @subhasisb on this. Unless the log message being introduced or being changed is an accounting log or something which gets displayed in say tracejob I would recommend not to put them in EDD.

#6

Thanks for the comments. Please keep them coming. I updated the line in question to read:

[Don’t] Document log messages unless required for end user documentation

#7

Thanks for the update @mkaro

#8

If you’re adding new log messages (or even changing old ones), then I think it should be documented somewhere that’s not in the code. Maybe in a source code guide?

I understand that some logs are not supported and can be changed at any time, but since we use those for testing things in pbs_benchpress, I don’t want to be grepping through the code.

I agree that the DDs are not the place to put them, but I think they need to go somewhere.

#9

PTL tests are synced with a particular branch/codeline of PBS, and in essence is part of the PBS source code. Since PTL is part of PBS source, my perspective is that log messages used by PTL are like internal interfaces. If there is a mismatch between tests and log messages, tests will fail. We would not need to grep for them. So I can’t see a reason to document them anywhere for the purpose of PTL.

Practically too, by the time one has documented a log message in any document, chances are the log message has changed in code…

#10

I think that in nearly all cases log messages should be self-documenting. By that I mean if the log message is not clear and concise, it probably shouldn’t be there to begin with. There are some cases where the context in which a message is issued could affect its meaning. In those cases, adding a comment in the code will help others understand both the necessity for and the meaning of the message.

#11

Your arguments make sense; I’ll concede.

On the broader topic, I agree with the changes to design documents.

#12

Final call for comments on the PBS Pro design document guidelines prior to adoption.

#13

Thank you all for your feedback. The design document guidelines have been posted here:

https://pbspro.atlassian.net/wiki/spaces/DG/pages/293076995/PBS+Pro+Design+Document+Guidelines

References to examples will be added as they become available.