fperez
commented
9 years ago There's no easy way to add line-number level comments to existing code, only commits. That's indeed one nice aspect of gdocs we don't have here.
One way to do it that I can think of is to put in those lines a change that reads [FIXME: ....]. Then it can be discussed in the PR in-line until a solution is reached.
Do you want to try that and see how it goes?
Added "What is a Method?" definition (edit as appropriate).
Fixed a few typos, improved punctuation and wording.
Is there any way to attach comments to specific text in the Markdown? That is very easy to do in googledocs but I don't see a good way to do it on GitHub. If I open a new issue, I just get a blank box with no context (i.e., I'm talking about this point in this file).
Some comments (by line number): Line 9: I think "Service that conforms to KBase typespec" (line 9) needs to be explained better. Do you mean conforms to a KBase typespec? Is defining the typespec the responsibility of the creator of this method, or are they supposed to use typespecs that already exist?
Line 18: Define and/or link out to NJS?
Line 32: Maybe for the first few "checkout" commands it would be useful to include the actual git command?
Line 39: Explain what you mean by dependencies. Modules that depend on this one, or modules that this one depends on?
Line 40: Provide link to license file
Line 41: "Your usual README file"--can you explain what should be in it?
Line 47: Should this say client rather than clients? I'm not sure whether to parse it as "clients, and server stubs" or (client and server) stubs.
Line 48: "Run the command with the -h flag" -- which command?
Line 52: "A new dependency, however, will not be available on test or production machines until the KBase runtime is rebuilt with your new changes, the last full build being Nov 2014." -- I don't understand how that last clause about Nov 2014 fits with the rest of this. Is there some schedule for these full builds? (Isn't it surprising that there wasn't one in Jan or Feb 2015??)
Line 57 - Needs more explanation.
Line 64 - "1. If you are the owner of the existing service, you can make changes directly to your service." -- Should they be submitting PRs, or are service owners allowed to just commit to their repos with no code review?
Line 73 - Somewhere in this vicinity you should warn that indenting matters in the method spec file and screwing up the indenting can have dire consequences.
78 - Is this true?
118 - "This looks like a much larger mess than it is." -- ha!