Here is an attempt to outline the steps I take when attempting to package an existing open source project for coapp.


Step 0: Set up all of the tools you need, and make sure they work.
 * Install coapp, coapp.devtools, the windows sdk, visual studio, mingw compilers, mingw-git (or some other git flavor if you prefer), and WiX.
 * Get a code-signing certificate set up, probably a self-signed cert for testing.
 * Get the source code for an existing coapp package, and make sure you can build it. MakeTestCert is a good one because it's simple. I would also suggest zlib, if it weren't for the complications of needing multiple compilers to properly build the "release" and "package" targets.

Step 1: Get the source code, and form a plan.
 * Search for the project on https://github.com/coapp-packages/. Try not to duplicate others' work.
 * Download the source code for the project you want to package. This can either be a source archive or a git repository. In some cases, you may want to use a source archive even if git is available. Some projects have generated files that are included in the source but not tracked in git, and those files can be difficult to generate on Windows. If the project uses any source control other than git, use release archives.
    * In the rare case of a project that does not release its source code in archive form and uses source control other than git, you will have to use that source control to get the source code and convert snapshots to git. Do not attempt to convert the repository to git. You should probably avoid this sort of project unless you're familiar with git and with the upstream source control.
 * Read the readme's, particularly anything Windows-specific. Figure out what this project's dependencies are, which of the dependencies are required, and which are optional. If the project has any required dependencies, they will have to be packaged first. To keep things simple, you may want to start by ignoring any optional dependencies and optional parts of the project that you don't really need.
 * Go back and make sure all the dependencies you need are packaged. If they're not, package them.

Step 2: Add the source code to Git.
 * If you got your source code by cloning a git repository, find the latest release.
    * By default, cloning a git repository will usually give you the bleeding-edge version, and we don't want that.
    * Use "git tag -l" to get a list of tags.
    * Go to the one you want, using "git checkout <name of tag>".
    * Create an "upstream" branch at that tag, using "git branch upstream". This branch will be used to keep track of the original versions of the project that you will modify.
    * Move the "master" branch to the same place, using "git branch -f master".
    * Check out the "master" branch so that further work you do will be added to that branch - "git checkout master".
 * Otherwise, make a new Git repository, extract your sources into it, commit the sources with no modifications, and make a branch named "upstream".

Step ?: Publish your work to Github.
 * You will probably find at some point during this process that you have done enough work that you would be sad if you lost it, and at that point you should push it to a Git repository. This could be the coapp-packages github, your own personal github, or some private server. I'm going to assume it's some form of github, and that if you have a private server for this you can figure it out.
 * If you retrieved your project's source code by cloning git, run "git remote rename origin upstream", so that you can add the repository you created on github as "origin" without causing confusion.
 * Create a repository by following the instructions at https://github.com/repositories/new (for your own github account) or https://github.com/organizations/coapp-packages/repositories/new (for coapp-packages, if you are a member of that organization). If the upstream project's git repository is on github, you should probably fork that instead.
  * If you do fork, delete the "master" branch from the new repository using github's web interface.
 * Add your new github repository as a remote named origin: "git remote add origin [email protected]:username/projectname.git". Replace "username" with your username, or coapp-packages if your new repository is in coapp-packages. Replace "projectname" with the project name you entered in github.
 * Publish your "master" branch, using "git push origin master".
 * Also publish your "upstream" branch, using "git push origin upstream".
 (I'm not going to go into updating the local repository with other people's work, or pushing further work, but it's a useful topic.)

Step 3: Get the project to build on Windows.
 * If no build process is necessary, skip this step.
 * For each required dependency, install the appropariate -dev package with coapp.
 * If there are Windows-specific build instructions, try them.
 * If you have dependencies, you will most likely need to configure the build with their location. Header files are located in c:\ProgramData\include\projectname. Library files are in c:\ProgramData\lib\x86.
 * If you have to modify any files to make the build work, stage them for the next commit using "git add <list of files>", review each change using "git diff --cached", and make the commit using "git commit". Try to make one logical change per commit, and make your commit messages descriptive. Make sure the commit message explains why you did what you did. Don't just restate what is already in the diff.
 * Try to avoid modifying existing files as much as possible. When adding new files, put them inside a directory named COPKG if possible.
 * If you add a Visual Studio project (in COPKG, of course), make sure you commit all .sln, .vcxproj, and .vcxprog.filters files, as well as any source files you've created. If your project includes files that will have to be updated manually for new releases, put a file in COPKG (perhaps COPKG/README) explaining how to do this.
 * Once you've built successfully, and all the changes needed to make it work are committed, use "git clean -nxd" to get a list of all of the files in your repository that are not tracked in Git. This should include all intermediate and final results of the build process. It MUST NOT include any files you added that are required for the build. If it does, commit them.
 * Decide which of the generated files (from "git clean -nxd") should be in your package. You will use this later to fill in the "targets" rule of your buildinfo file.
 * For .dll and .exe files that you want to package, use dependency walker to check what .dll files they depend on. All of them should either be part of the package you are working on, part of a package it will depend on, or part of Windows.

Step 4: Create the .buildinfo file, so the project can be built with ptk.
 * Create a COPKG/version.inc file containing something like the following:
    #define { package-version: 1.3.0.1; }
    #define { upstream-version: 1.3; }
   Author-version is the version number exactly as written by the upstream project. Package-version is a translation of that version into four integers separated by dots. Package-version must be a reliable way to compare versions of the project. The last number of package-version is used to distinguish between revisions of packages for the same version of the original project. If you need to be creative to make the package-version, please make a comment explaining the rules you use.
 * Add boiler-plate stuff to COPKG/.buildinfo:
    @import "version.inc";
    #product-info
    {
        product-name: "libknotty";
        version: "$upstream-version";
        original-source-location: "http://libknotty.org/files/libknotty-1.3.tar.gz";
        original-source-website: "http://libknotty.org/download";
        license: "Artistic License";
        packager: "Your Name <[email protected]>";
    }
 * Add a description of the build process:
    targetname
    {
        compiler: vc10;
        platform: x86;
        targets:
        {
            @"COPKG\libknotty\Release\libknotty.dll",
            @"COPKG\libknotty\Release\libknotty.lib",
            @"COPKG\libknotty\Release\knots.exe"
        };
        build-command: @"
            msbuild /p:Platform=Win32 /p:Configuration=Release COPKG\libknotty\libknotty.sln
        ";
        clean-command: @"
            msbuild /target:Clean /p:Platform=Win32 /p:Configuration=Release COPKG\libknotty\libknotty.sln
        ";
    }
   You can replace "targetname" with a more descriptive name.
   The "targets" are the files generated by the build that you will need later, usually those that you will put in a package. Ptk will know something went wrong if all of the targets do not exist at the end of the build process.
   If you did not use Visual Studio or Mingw in your build process, omit the "compiler" and "platform" lines.
   The build-command section is a cmd-style list of the commands needed to build your target. If you did your build in Visual Studio, your build-command will use msbuild.
   The clean-command section is a cmd-style list of the commands needed to remove all the files generated by your build.
 * Test using "ptk build targetname".
 * If it seems to work, "git add COPKG/version.inc COPKG/.buildinfo" and commit.
 * Test using "ptk verify targetname", make any further necessary fixes (usually to clean-command), and commit.
 * Add a release target, like this:
    release
    {
        uses: targetname;
    }
 * Test "ptk build release", and commit.

When it comes to building the autopkg descriptions, I haven't really settled on a process yet. Mostly I just copy the things I need from zlib packages. Probably the best thing here is to have examples for simple cases (somewhat inspired by some of the gsoc discussion on an autopackage gui tool):
 * Make a .autopkg file that makes an empty, but functional package.
 * Package a .exe file with no dependencies, such that it will be in the PATH.
 * Package a .dll file with no dependencies, including an assembly so other exes/dlls can use it.
 * Create a manifest for a .exe or .dll file, so that it can make use of other dll's in the same packages that have an assembly.
 * Add a dependency with the "requires" rule, so that manifests in a package can use the assemblies in the required package.
 * Create a menu shortcut for a .exe.
 * Create a -dev-common package containing headers and/or docs.
 * Create a -dev package containing a .lib file.
 * Add .autopkg files to the "package" target in ptk.