Open apowers313 opened 9 years ago
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:
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:
npm install -g semantic-release-cli
cd your-module
semantic-release-cli setup
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'].
semantic-release-cli performs the following steps:
--no-keychain
was specified)npm adduser
with the npm information provided to generate a .npmrc
.npmrc
for future usebefore_install: npm i -g npm@^2.0.0
: install NPM 2before_script: curl -Lo travis_after_all.py https://git.io/vLSON
: install travis-after-all script to enable running semantic-release
after ALL build succeedafter_success: python travis_after_all.py
and npm run semantic-release
: run semantic-release
exactly once after all builds passsudo: false
, cache: directories: node_modules
, notifications: email: false
, before_script: npm prune
version
field (you don't need it anymore -- semantic-release
will set the version for you automatically)semantic-release
script: "semantic-release": "semantic-release pre && npm publish && semantic-release post"
semantic-release
as a devDependency
repository
fieldBy 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.
MIT License 2015 © Christoph Witzko and contributors
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.
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:
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.
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.
From semantic-release/semantic-release#82:
In addition to reversing the default for
keychain
, it would be good to see a clearly enumerated set of steps thatsemantic-release-cli
takes when configuring a repository. When I was shopping around for release scripts, I liked the way thatrelease-script
documented their process.This probably applies to
semantic-release
andsemantic-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.