doc: update os.uptime() and process.uptime() descriptions

[vsemozhetbyt]

Checklist

• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

doc, os

Fixes: #12291

[refack]

I would phrase it as:
-*Note*: On Windows (and maybe other platforms as well) the value returned includes fractions of a second.

[gibfahn]

(and maybe other platforms as well)

The docs are the canonical source for what our API does, we should be exact. I don't think there are any other platforms that do fractions of a second, but if there are, we can update the docs.

[refack]

we should be exact.

@gibfahn I agree in principle, can we figure this out exactly? Until recently we had a hard time list all supported platform (#11872). Mentioning Windows has an implicit meaning that it's only on Windows. And as @bnoordhuis said

UNIX implementations of that function don't currently bother to mix in the sub-second fraction. That could change in the future though, if someone requests it.

[refack]

So:
-*Note*: The value returned may include fractions of a second (on Windows it consistently does, on others it's not defined).

[gibfahn]

I checked macOS, Ubuntu 16.04, SmartOS 16, FreeBSD 11, and AIX 6.1, and they're all consistent (os.uptime() is an integer, process.uptime() is not). Given that, I'd say we're okay to specify that it's just Windows.

If it changes in the future then the PR to change it should update the docs, making it a semver-major change.

[refack]

-*Note*: The value returned may include fractions of a second (on Windows it consistently returns a float. Other platforms currently returns an integer but may change in the future).

[refack]

PR to change it should update the docs, making it a semver-major change.

It might get changed by the OS, under us

[vsemozhetbyt]

@refack Could you repeat the proposed wording in the main thread? Somebody may not look in the outdated discussion.

[refack]

maybe add the same to process.md:1669

[vsemozhetbyt]

@refack process.uptime() doc does not state to return integer and it is the same for all OS, it seems.

[gibfahn]

maybe add the same to process.md:1669

@vsemozhetbyt You could just include this bit in process.md:

Note: the return value includes fractions of a second. Use Math.floor() to get whole seconds.

[vsemozhetbyt]

Is (and maybe some other platforms as well) OK?

[refack]

@vsemozhetbyt No. I've rephrased, and would wait for a +1 from some else
/cc @gibfahn @bnoordhuis

[refack]

gibfahn 8 minutes ago • edited Member
I checked macOS, Ubuntu 16.04, SmartOS 16, FreeBSD 11, and AIX 6.1, and they're all consistent (os.uptime() is an integer, process.uptime() is not). Given that, I'd say we're okay to specify that it's just Windows.

If it changes in the future then the PR to change it should update the docs, making it a semver-major change.

refack 5 minutes ago • edited Member
-Note: The value returned may include fractions of a second (on Windows it consistently returns a float. Other platforms currently returns an integer but may change in the future).

refack 4 minutes ago Member
PR to change it should update the docs, making it a semver-major change.
It might get changed by the OS, under us

Proposing:
-*Note*: The value returned may include fractions of a second (Windows consistently returns a float. Other platforms currently return a whole number, but may change this behaviour in the future).

[refack]

I have too many lawyer friends...

[gibfahn]

It might get changed by the OS, under us

I'm pretty sure the UNIX implementations @bnoordhuis is talking about in #12291 (comment) are in libuv, not in the OS itself. So it can only change in a libuv update (which would need to update the docs).

EDIT: e.g. here

See also libuv/libuv@556fe1a

[refack]

are in libuv, not in the OS itself

Let me look...

[refack]

are in libuv, not in the OS itself

yep, saw it.

So phrase:
*Note*: On Windows the returned value includes fractions of a second...

[refack]

Ref: libuv/libuv#1294

[vsemozhetbyt]

I've updated according to the last proposition for now.

@nodejs/documentation PTAL

[jasnell]

Landed in 9b6376a

[MylesBorins]

Can someone confirm that that is true for v6.x

[gibfahn]

Can someone confirm that that is true for v6.x

ping @vsemozhetbyt

[vsemozhetbyt]

@gibfahn It seems this is true for the last v6. Does this land cleanly or should I make a backport PR?

[gibfahn]

Lands cleanly