Go-ipfs: some profile are missing in the ipfs init command documentation

[MichaelMure]

Version information:

go-ipfs version: 0.4.14-rc2-
Repo version: 6
System version: amd64/linux
Golang version: go1.10rc2

Type:

Bug

Description:

ipfs init --help list only 2 profiles (server and test) while more actually exist (https://github.com/ipfs/go-ipfs/pull/4195/files#diff-d39a8a737bc5c13f36e41aa92a0c7602). Ideally, this documentation would be generated to be always up to date.

Additionally, profile coule be listed in ipfs config profile apply as well.

[Kubuxu]

We should probably list them in some help text of the ipfs config profile command and refer to that in ipfs init help.

[nothingismagick]

Alternatively, you could ask the user what kind of init they would like to undertake from the list of available profiles. I was not aware of all of these modes either, and had go-ipfs asked me when I ran ipfs init if I wanted to use e.g. the server profile, I would not have been slapped with an abuse notice from Hetzner today. Seeing as this exact thing is still happening 3 years after it was first made an issue - and is even happening to core ipfs people like @ZenGround0 - perhaps it is time to require that the user choose a mode. Just saying...

[Kubuxu]

@nothingismagick Requiring user interaction on init would break many existing scripts including our owns.

[nothingismagick]

@Kubuxu - which existing scripts exactly? Please share some with me, so I can see what you mean. I can only guess that you are talking about automated setup, for things like electron apps in IPFS-Desktop.

Technically, in my case IPFS did require user interaction, but I didn’t know it. I should have set flags in the command invocation, which is user interaction in my playbook. Because I didn’t do it, my service provider threatened to remove my server from the internet. This is a way in which the script would have broken itself (actually the entire ecosystem in which it lived) because of a poor user-interaction methodology. Sure, it is a mistake I will never make again, but how can I guarantee that it never happens to anyone on my large and growing team?

This is one seriously critical gotcha that I cannot merely write-off because it would ‘break many existing scripts’ - it almost broke my uplink and cost me an afternoon of writing compliance reports. I don’t even want to think what this is doing to the broader image of IPFS for providers... Anyway, until this gets sorted, I will write a wrapping init script and require that all of my org users take that approach, but this will mean that I have to maintain the build script as IPFS evolves. And so the technical debt begins...

At the end of the day, however, this is an upstream problem. Maybe require seems like too strong a word, but I require that vendor scripts in typically sane default settings do not nuke my server. There are ways to introduce interactivity without breaking anything, such as offering and (recommending) an --interactive flag to the init process. Another approach would be to start with an interactive setup and have a 5 second timeout, so as not to break existing scripts. What do you think @flyingzumwalt ?

[nothingismagick]

[magik6k]

We can detect if init is invoked from tty or a script and enter interactive mode based on that

[Kubuxu]

@nothingismagick it would break every docker container out there (if they would re-init), all of our tests, compatibility tests in js-ipfs, iptb and so on.

There is a lot of this.

We can detect if init is invoked from tty or a script and enter interactive mode based on that

Changing behaviour of a command basing on tty is not a good idea. It leads to more UI confusion.
Imagine people doing echo server | ipfs inti.

Another point is that it would be very hacky to do with our command framework and ipfs init already accepts stdin as a template of a config.

---

@nothingismagick could you put the picture in \https://gist.github.com/ericclemmons/b146fe5da72ca1f706b2ef72a20ac39d

Also I disagree with it quite a bit, in this case user is just not looking at the UI (the UI is arguments and helptext).

[Kubuxu]

@nothingismagick if you want to discuss it further please open a separate issue because this is out of the scope of this one.

[nothingismagick]

Sorry about the thread-jacking, I merely wanted to make the strong case that the documentation is generally confusing, disjointed and this can have real-world repercussions.

[nothingismagick]

And there was a thread about this (that I linked above), where I would have posted, but it has been closed to non-contributors.

[nothingismagick]

Regarding your disagreement, perhaps we are misunderstanding each other. In the universe that is interaction design, every interface to the code that the user has, is UI per definition - including the command line. Indeed, Go-IPFS is giving user feedback on IPFS init (a peer-ID). If you look at the image hidden in the details tag, you will also see a logo and a typical screenshot of the install process. I understand the alpha nature of the software, but this is a critical onboarding moment and as such it is possibly the last direct interaction that the user will have with the underlying code-base. Not a moment to squander, in my opinion.

My point is that the helptext is incomplete, which is the whole purpose of this issue: there is an underlying (and deep-seated problem) here about the hygiene of help texts and documentation in general within the scope of the entire project.

---

EDIT: Fixed the image - Kubuxu

[Mr0grog]

Since this has gotten a little off the main topic (get all the profiles listed in the help text), I started a new issue to continue discussion about an interactive init command: https://github.com/ipfs/go-ipfs/issues/4877

[nothingismagick]

For the record, here is a link to the discussion about documentation in general:

https://ipfs.io/ipns/ipfs-docs-research.robbrackett.com/html/General-Notes.html