CONVENTIONS: update to include general public API principles

This got lost duing the move and it lets the users call this function
just in case.

Minor `giterr` fixups

The `giterr_set_str` does not actually honor `GITERR_OS`.  Remove
the documentation that claims that we do.

Use the `giterr_set` function, which actually supports `GITERR_OS`.
The `giterr_set_str` function is exposed for external users and will
not append the operating system's error message.

git_libgit2_opts: minor documentation & usage fixes

Fix a few checkout -> rebase typos

We need to include the header where we define the function. Otherwise it
won't be available on the DLL.

Filter registration

Coverity fixes

When checking for out of memory situations we usually use the
GITERR_CHECK_ALLOC macro. Besides conforming to our current code
base it adds the benefit of silencing errors in Coverity due to
Coverity handling the macro's error path as abort.

When checking if a string is prefixed by a drive letter (e.g.
"C:") we verify this by inspecting the first and second character
of the string. Coverity thinks this is a defect as we do not
check the string's length first, but in fact we only check the
second character if the first character is part of the alphabet,
that is it cannot be '\0'.

Fix this by overriding the macro and explicitly checking the
string's length.

Add nodefs for macros that abort the current flow due to errors.
This includes macros that trigger on integer overflows and for
the version check macro. This aids Coverity as we point out that
these paths will cause a fatal error.

Handle `USE_NSECS` 

win32: drop xp support in WideCharToMultiByte

Remove most of the silly warnings

win32: allow us to read indexes with forbidden paths on win32

Fix a typo

`compatability` → `compatibility`

Allow `git_index_read` to handle reading existing indexes with
illegal entries.  Allow the low-level `git_index_add` to add
properly formed `git_index_entry`s even if they contain paths
that would be illegal for the current filesystem (eg, `AUX`).
Continue to disallow `git_index_add_bypath` from adding entries
that are illegal universally illegal (eg, `.git`, `foo/../bar`).

Although a `tree_iterator` that failed to be properly created
does not have a frame, all other `tree_iterator`s should.  Do not
call `pop` in the failure case, but assert that in all other
cases there is a frame.

When Git repository at network locations, sometimes git_iterator_for_tree
fails at iterator__update_ignore_case so it goes to git_iterator_free.
Null pointer will crash the process if not check.

Signed-off-by: Colin Xu <colin.xu@gmail.com>

Introduce a repository that contains some paths that were illegal
on PC-DOS circa 1981 (like `aux`, `con`, `com1`) and that in a
bizarre fit of retrocomputing, remain illegal on some "modern"
computers, despite being "new technology".

Introduce some aspirational tests that suggest that we should be
able to cope with trees and indexes that contain paths that
would be illegal on the filesystem, so that we can at least diff
them.  Further ensure that checkout will not write a repository
with forbidden paths.

commit: expose the different kinds of errors

We should be checking whether the object we're looking up is a commit,
and we should let the caller know whether the not-found return code
comes from a bad object type or just a missing signature.