coapp-developers team mailing list archive

[Vincent Povirk <madewokherd@xxxxxxxxx>]

I've come up with a list of things that I try to do when shallow
forking and that I think are the "officially endorsed" or failing that
"correct" way of doing things. I'm not sure where it properly belongs,
and maybe some people wouldn't agree on all of these. Also, maybe some
of you have things to add. So I thought I'd bring it up for
discussion.

Here's the list:
* Always have your Git configured with your name and email address,
and set core.autocrlf to 'false'.
* Always fork the original project you want to port. Do not fork a
fork of it, like gnuwin32 or unxutils.
* If the project keeps its source code in Git, fork their Git
repository, unless you have a good reason not to (such as needing
generated files that are only present in tarballs).
* When forking a project's Git, build your fork on top of a release
tag. Don't just put it at whatever the latest commit happens to be.
* If a project does not keep its source code in Git, use vendor
branches to track it. (See
http://happygiraffe.net/blog/2008/02/07/vendor-branches-in-git/) You
should have one branch containing pristine source code and one
containing your changes.
* The "original-source-location" should be a git: url if you cloned a
git repository, or a url to the source package you downloaded. (If you
had to import a revision directly from another VCS, you are charting
new territory. Do what you think is best, then try to establish a
policy around it.)
* When possible, build using MSVC.
* When possible, use build files maintained by the original project.
NMake, CMake, and SCons can all use the MSVC compiler.
* When possible, avoid modifying existing files.
* If you do have to modify an existing file, consider sending the
change upstream. This does mean you have to make the change cleanly so
it can be accepted. (I have not actually done this yet, but I think
the ideal is for our forks to be identical to upstream outside of
COPKG.)
* If you have to add files, put them in the COPKG directory if possible.
* Always use the "git merge" command to update the fork with new releases.
* Ideally, your fork shouldn't require anything to build except the
Windows SDK, Visual Studio, and mingw with only the compilers (no
libraries). All other build dependencies should be buildable through
ptk, and your fork should be able to make use of them. If your build
process uses a program like perl, add a commented uses statement for
that project, and add it to the path (like this: set
PATH=%PATH%;%CD%\..\perl) so that one has the option of building perl
with ptk or installing perl in another way and making sure it is in
the path.
* Add a commented uses statement if you require the code from another
project but no generated files. (Should there be a real way to express
this in .buildinfo?)
* Corollary: If you don't need mingw for anything but coapp, you
should install it with only the compilers.
* Visual Studio likes to apply changes to only the active
configuration (debug or release) and platform (x86 or x64). Usually,
you will want to edit all configurations and platforms, so make sure
you select that in those cases.
* If a project needs headers/functions that are available in gcc as
part of the standard library but are not available in MSVC, consider
using gnulib (coapp-packages has a fork of it, though there is no
build process because it is a source library) for a replacement. It is
designed for this sort of thing, and other solutions in use (besides
mingw) tend to be unmaintained. You will need to add gnulib\lib to
your include path and a C file in gnulib\lib for any functions your
program needs. You may also need to modify the headers in gnulib\lib
or define some symbols in your project.