Keychain usage / documentation

[apowers313]

From semantic-release/semantic-release#82:

I found the undocumented use of keytar extremely disturbing when I realized that semantic-release-cli had saved my passwords without mentioning that was going to do so in the README or mentioning it as part of install script. The README doesn't even mention the command-line option for --no-keychain. I would advocate for defaulting keychain to false and updating the README. Happy to submit a PR if you guys are open minded to that.

In addition to reversing the default for keychain, it would be good to see a clearly enumerated set of steps that semantic-release-cli takes when configuring a repository. When I was shopping around for release scripts, I liked the way that release-script documented their process.

This probably applies to semantic-release and semantic-release-cli equally -- if I am going to trust you to write to my repositories you better be pretty damn clear about what you are going to do or I'm not going to trust you.

[jo]

Hi, thats good input, thanks! I absolutely agree that we need better documentation, especially for the keychain usage. I would happily review a PR :smile:

[apowers313]

Rather than iterating through pull requests, I figure I would ask for feedback here first. Here's what the new README.md would look like -- please let me know what you think about the format and the accuracy of the information:

---

semantic-release-cli

Install

npm install -g semantic-release-cli

cd your-module
semantic-release-cli setup

Options

Usage:
  semantic-release-cli setup [--tag=<String>]

Options:
  -h --help           Show this screen.
  -v --version        Show version.
  --[no-]keychain     Use keychain to get passwords [default: true].
  --ask-for-passwords Ask for the passwords even if passwords are stored [default: false].
  --tag=<String>      npm tag to install [default: 'latest'].

What it Does

semantic-release-cli performs the following steps:

1. Asks for the information it needs. You will need to provide it with:
   • Whether your GitHub repository is public or private
   • Which NPM registry you want to use (Default: https://registry.npmjs.org/)
   • Your NPM username (unless passwords were previously saved to keychain)
   • Your NPM email
   • Your NPM password
   • Your GitHub username
   • Your GitHub password (unless passwords were previously saved to keychain)
   • Which continuous integration system you want to use. (Options: Travis CI / Pro / Enterprise, or Other)
   • Whether you want to test a single node.js version (e.g. - 0.12) or multiple node.js versions (e.g. - 0.10, 0.12, etc.)
2. Save your passwords to your local OS's keychain using keytar for future use (unless --no-keychain was specified)
3. NPM Add User
   • Runs npm adduser with the npm information provided to generate a .npmrc
   • Parses the NPM token from the .npmrc for future use
4. Create GitHub Personal Token
   • Logs into GitHub using the username and password provided
   • Creates a GitHub Personal Access Token and saves it for future use
5. Overwrite your .travis.yml file (if Travis CI was selected)
   • before_install: npm i -g npm@^2.0.0: install NPM 2
   • before_script: curl -Lo travis_after_all.py https://git.io/vLSON: install travis-after-all script to enable running semantic-release after ALL build succeed
   • after_success: python travis_after_all.py and npm run semantic-release: run semantic-release exactly once after all builds pass
   • Set other sane defaults: sudo: false, cache: directories: node_modules, notifications: email: false, before_script: npm prune
6. Update your package.json
   • Remove version field (you don't need it anymore -- semantic-release will set the version for you automatically)
   • Add a semantic-release script: "semantic-release": "semantic-release pre && npm publish && semantic-release post"
   • Add semantic-release as a devDependency
   • Add or overwrite the repository field
7. Login to Travis CI to configure the package
   • Enable builds of your repo
   • Add GH_TOKEN and NPM_TOKEN environment variables in the settings

Other CI Servers

By default, semantic-release-cli supports the popular Travis CI server. If you select Other as your server during configuration, semantic-release-cli will print out the environment variables you need to set on your CI server. You will be responsible for adding these environment variables as well as configuring your CI server to run npm run semantic-release after all the builds pass.

Note that your CI server will also need to set the environment variable CI=true so that semantic-release will not perform a dry run. (Most CI services do this by default.) See the semantic-release documentation for more details.

License

MIT License 2015 © Christoph Witzko and contributors

[apowers313]

By the way, that image of the configuration process seems to be really out of date. Could whoever created that one create a new one?

Also, it would be great if those info messages found their way back into the config process for the sake of UX affordance and safe exploration.

[boennemann]

Hey @apowers313,

Sorry for the late reply, I didn't really have internet the past week. First of all thanks so much for this, this is very valuable feedback and a very valuable contribution to the README.md.

Here are my thoughts on this:

keychain caching

First of all I'm apologizing for using this as a default, without being explicit about it. The excitement about this contribution dominated the ability to think about unintended and very unpleasant side effects of this technique.

I think, however, that just reversing the default isn't the best solution. I'd prefer to ask the user whether they'd like to cache their credentials in the keychain on first run, and then persist the answer on the local filesystem, which should be a more convenient way of using it for both choices.

I think it would be a good match to use rc (I've already successfully used this elsewhere) to read these config files from e.g. the homedir.

It would make sense to persist other things there as well (npm registry, usernames) and adding a --yes/-y flag just like npm init has it, which just runs the whole thing using the defaults. This should get us to the point where we can run the setup w/o a single question on second run.

adding a list of steps to the README.md

This is a very good effort. I already had the list of manual steps in the README.md so it's clear what is necessary/happening, but I'm all for making it even clearer and more detailed. The info logs were never gone though. Following the unix philosophy's rule of silence the default loglevel is set to "warn". Currently the semantic-release-cli is inheriting the loglevel from npm, which means running e.g. npm_config_loglevel=info semantic-release-cli setup will bring them back at any time. I think that inheriting npm's loglevel is a very good default, but I'm all up for adding an additional loglevel flag so it's possible to set it on the semantic-release-cli level. The updated screenshot is already used in the main repo: https://cloud.githubusercontent.com/assets/908178/9428123/3628dfec-499f-11e5-8bdd-8f3042dd95ed.png

That all being said I think this issue at least addressing two separate things now.

I think it would make most sense to open a PR with the new readme applied, which offers an excellent interface for iterating and giving feedback, before merging it in.

For the defaults and persistent config parts we should open a separate issue.