Troubleshooting ... some lessons learnt

doc/05-repositories.md

@@ -154,7 +154,7 @@ VCS stands for version control system. This includes versioning systems like
 git, svn or hg. Composer has a repository type for installing packages from
 these systems.
 
-#### Maintaining a third library fork
+#### Maintaining a third party library fork
 
 There are a few use cases for this. The most common one is maintaining your
 own fork of a third party library. If you are using a certain library for your

doc/articles/troubleshooting.md

@@ -1,7 +1,42 @@
 <!--
     tagline: Solving problems
 -->
-# Memory limit errors
+# Troubleshooting
+
+This is a list of common pitfalls on using Composer, and how to avoid them.
+
+## General
+
+1. When facing any kind of problems using Composer, be sure to **work with the
+   latest version**. See [self-update](03-cli.md#self-update) for details.
+
+2. Ensure you're **installing vendors straight from your `composer.json`** via
+
+~~~~
+    rm -rf vendor && composer update -v
+~~~~
+
+   when troubleshooting, excluding any possible interferences with existing
+   vendor installations or `composer.lock` entries.
+
+## Package not found
+
+1. Double-check you **don't have typos** in your `composer.json` or repository
+   branches and tag names.
+
+2. Be sure to **set the right
+   [minimum-stability](04-schema.md#minimum-stability)**. To get started or be
+   sure this is no issue, set `minimum-stability` to "dev".
+
+3. Packages **not coming from [Packagist](http://packagist.org/)** should
+   always be **defined in the root package** (the package depending on all
+   vendors).
+
+4. Use the **same vendor and package name** throughout all branches and tags of
+   your repository, especially when maintaining a third party fork and using
+   `replace`.
+
+## Memory limit errors
 
 If composer shows memory errors on some commands:
 
@@ -16,7 +51,8 @@ Get current value:
 
     php -r "echo ini_get('memory_limit').PHP_EOL;"
 
-Increase limit with `php.ini` for a `CLI SAPI` (ex. `/etc/php5/cli/php.ini` for Debian-like systems):
+Increase limit with `php.ini` for a `CLI SAPI` (ex. `/etc/php5/cli/php.ini` for
+Debian-like systems):
 
     ; Use -1 for unlimited or define explicit value like 512M
     memory_limit = -1