Reformulate installation guidelines and add section about proxies #783
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Aim of the changes is to be less verbose about technical details and to be more action-oriented then prose-oriented in the text.
abtris
approved these changes
May 16, 2017
miiila
reviewed
May 16, 2017
docs/installation.md
Outdated
|
|
||
| Dredd sometimes issues a pre-release version to test experimental features or to ensure that significant internal revamp of existing features didn't cause any regressions. It's possible to use `npm install dredd@stable` to avoid installing the pre-release versions. However, for most of the time, there are no pre-releases and the `stable` tag just points to the latest version. | ||
| ### Why I'm Seeing Network Errors? |
docs/installation.md
Outdated
|
|
||
| #### Compiled vs pure JavaScript | ||
| If you're in restricted network (VPN, firewall, proxy), it's possible you see errors similar to the following ones: |
There was a problem hiding this comment.
in a restricted network... you can see errors
.github/CONTRIBUTING.md
Outdated
| @@ -86,6 +86,17 @@ Also mind that CoffeeScript is production dependency (not dev dependency), | |||
| because it's needed not only for compiling Dredd package before uploading | |||
| to npm, but also for running user-provided hooks written in CoffeeScript. | |||
|
|
|||
| ### Compiled vs pure JavaScript | |||
|
|
|||
| Dredd uses [Drafter][] for parsing [API Blueprint][] documents. Drafter is written in C++11 and needs to be compiled during installation. Since that can be problematic for some environments and leads to a lot of troubleshooting, there's also pure JavaScript version of the parser, [drafter.js][]. While drafter.js is fully equivalent, it can have slower performance. That's why there's [drafter-npm][] package, which first tries to compile the C++11 version of the parser and if it's unsuccessful, uses the JavaScript equivalent. | |||
There was a problem hiding this comment.
Because this can cause a lot of troubles in some environments, there's also...
Drafter.js is fully equivalent, but it can have slower performance.
Therefore there's...
which tries to compile the C++11 version of the parser and uses the JavaScript equivalent in case of failure
.github/CONTRIBUTING.md
Outdated
|
|
||
| Dredd uses [Drafter][] for parsing [API Blueprint][] documents. Drafter is written in C++11 and needs to be compiled during installation. Since that can be problematic for some environments and leads to a lot of troubleshooting, there's also pure JavaScript version of the parser, [drafter.js][]. While drafter.js is fully equivalent, it can have slower performance. That's why there's [drafter-npm][] package, which first tries to compile the C++11 version of the parser and if it's unsuccessful, uses the JavaScript equivalent. | ||
|
|
||
| Dredd depends on the [drafter-npm][] package. That's why you can see `node-gyp` errors and failures during Dredd installation, although after the installation is done, Dredd seems to normally work and correctly parses API Blueprint documents. Usual problems leading to the JavaScript version of the parser being used as fallback: |
There was a problem hiding this comment.
That's the reason why you can see node-gyp errors and failures...
even though installation ended correctly and Dredd...
Last sentence doesn't make sense for me - are you trying to fix this issues? Is it necessary if it seems to be working? I would appreciate more explanation on the goal you want to achieve with the following list.
honzajavorek
force-pushed
the
honzajavorek/restricted-network
branch
from
3c53fd9
to
4c9db42
Compare
honzajavorek
force-pushed
the
honzajavorek/restricted-network
branch
from
4c9db42
to
fb14e6a
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
🚀 Why this change?
Installation of Dredd in restricted environment isn't completely straightforward. I added a section about the necessary steps. At the same time, I tried to simplify other sections as well and to make them more use-case-oriented.
📝 Related issues and Pull Requests
✅ What didn't I forget?
npm run lint