For years, we've repeatedly had confusion about what our actual coding
style is not only for newcomers, but also across the core contributors.
This can mostly be attributed to the fact that we do not have any coding
conventions written down. This is now a thing of the past with the
introduction of a new document that gives an initial overview of our
style and most important best practices for both our C codebase as well
as for CMake.
While the proposed coding style for our C codebase should be rather
uncontroversial, the coding style for CMake might be. This can be
attributed to multiple facts. First, the CMake code base doesn't really
have any uniform coding style and is quite outdated in a lot of places.
Second, the proposed coding style actually breaks with our existing one:
we currently use all-uppercase function names and variables, but the
documented coding style says we use all-lowercase function names but
all-uppercase variables.
It's common practice in CMake to write variables in all upper-case, and
in fact all variables made available by CMake are exactly that. As
variables are case-sensitive in CMake, we cannot and shouldn't break
with this. In contrast, function calls are case insensitive, and modern
CMake always uses all-lowercase ones. I argue we should do the same to
get in line with other codebases and to reduce the likelihood of
repetitive strain injuries.
So especially for CMake, the proposed coding style says something we
don't have yet. I'm fine with that, as the document explicitly says that
it's what we want to have and not what we have right now.
Give the release a name, "Torschlusspanik" (the fear that time is
running out to act). Indeed, the time is running out for changes to be
included in v1.0.
I encountered some problematic URLs,
and was delighted to see that they were already fixed.
I figured I may as well add them to the changelog.
For the record, URLs with no path used to be rejected.
That is arguably correct, but command line git accepts them.
URLs with a path of / and a non-standard port
used to have their port completely ignored!
The interactions between `USE_HTTPS` and `SHA1_BACKEND` have been
streamlined. Previously we would have accepted not quite working
configurations (like, `-DUSE_HTTPS=OFF -DSHA1_BACKEND=OpenSSL`) and, as
the OpenSSL detection only ran with `USE_HTTPS`, the link would fail.
The detection was moved to a new `USE_SHA1`, modeled after `USE_HTTPS`,
which takes the values "CollisionDetection/Backend/Generic", to better
match how the "hashing backend" is selected, the default (ON) being
"CollisionDetection".
Note that, as `SHA1_BACKEND` is still used internally, you might need to
check what customization you're using it for.
Our bundled http-parser includes bugfixes, therefore we should prefer
our http-parser until such time as we can identify that the system
http-parser has these bugfixes (using a version check).
Since these bugs are - at present - minor, retain the ability for users
to force that they want to use the system http-parser anyway. This does
change the cmake specification so that people _must_ opt-in to the new
behavior knowingly.
Previously, we would clobber any extension-specific error message with
an "extension is truncated" message. This makes `read_extension`
correctly preserve those errors, takes responsibility for truncation
errors, and adds a new message with the actual extension signature for
unsupported mandatory extensions.
While our contribution guide tries to make clear the licenses that apply
to libgit2, it does not make clear that different licenses apply to our
bundled dependencies. Make this clear by listing each dependency
together with the licenses that they are governed by. Furthermore,
bundle the complete license texts next to the code they apply to.
Both the USE_SANITIZER and USE_COVERAGE options are convenience options
that turn on a set of CFLAGS. Despite our own set of CFLAGS required to
build libgit2, we have no real business to mess with them, though, as
they can easily be passed in by the user via specifying the CFLAGS
environment variable. The reasoning behind not providing them is that as
soon as we start adding those for some usecases, users might ask for
other sets of CFLAGS catering to their specific need in another usecase.
Thus, we do not want to support them here.
Right now, users are being instrucded to add the
"-DCMAKE_EXE_LINKER_FLAGS=-fsanitize=fuzzer" flag when they want to
build our fuzzers. This is error-prone and user unfriendly. Instead,
just add the flag to our fuzzers' build instructions so that it happens
automatically. Adjust the README accordingly.
The libgit2 project mostly follows the coding style of git and thus
the linux project. While those two projects use a recommended tab width
of eight spaces, we instruct users to set their editor's tab width to
four spaces. Fix this to say eight instead.
We've introduced a manifest for the clib version system that includes a
version number; we should update it at release time to correspond with
the version number in the header.
Our non-technical documents are currently floating around loosely in our
project's root, making it harden than necessary to discover what one is
searching for. We do have a "docs/" directory, though, which serves
exactly that purpose of hosting documentation.
Move our non-technical documentation into the "docs/" directory. Adjust
all links to these documents.
