[Pkg-javascript-commits] [typescript-types] 04/04: Add documentation on out-of-sync packages

[Ximin Luo]

This is an automated email from the git hooks/post-receive script.

infinity0 pushed a commit to branch master
in repository typescript-types.

commit cf7b1bf532db4285f5c6b6770abe00d65ea991cf
Author: Ximin Luo <infinity0 at debian.org>
Date:   Fri May 19 20:04:27 2017 +0200

    Add documentation on out-of-sync packages
---
 debian/README.Debian | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/debian/README.Debian b/debian/README.Debian
index c96d2e4..19cfb78 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -5,6 +5,12 @@ Right now we only package a subset of what upstream has, because it would be
 crazy to package it all in one Debian package. However, feel free to extend
 this subset within reason.
 
+Caveats
+=======
+
+Out-of-sync with Debian
+-----------------------
+
 Sometimes the type definitions here are out-of-sync with the corresponding
 javascript library in Debian. This is an inherent flaw with the upstream
 package as well as the surrounding ecosystem; this cannot be fixed in Debian.
@@ -12,3 +18,22 @@ However, most of the time it should still work, i.e. the typechecks should
 still succeed with the (likely newer) types in this package, and the overall
 behaviour should be unaffected. If this doesn't work out for you, please file a
 bug to the upstream package to fix the situation on their end.
+
+Out-of-sync with each other
+---------------------------
+
+Yes, this is the shoddy nature of the npm ecosystem.
+
+If you blindly link the whole of /usr/lib/nodejs/@types to node_modules in
+your package's source or build directory, you *may* get spurious build failures
+like "Cannot find name [some core Javascript thing, like Array or Promise]".
+
+This is very likely due to the fact that types from some packages are
+targetting different versions of TS, or JS, or whatever. Instead, you should
+create a node_modules directory and link only specific subdirectories of
+/usr/lib/nodejs/@types into it (check your package.json for @types/*
+devDependencies), and point your package build to this.
+
+If you still get failures, check the declared versions. If they significantly
+mismatch the nes packaged here, file a bug report about it and we will try to
+figure out a solution.

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/typescript-types.git