[Stk] proposal for stk git repository layout

[Gary Scavone]

I agree with Stephen on the use of branches for releases.  I took a look at the github "release workflow" and it is not clear it would support all the extra release components in the way we want.  For example, it says you can attach binaries to a release by drag/dropping them into a particular window, but it is not clear that it would put our extra components (configure script, html documentation, …) in the correct locations within the distribution (rather than simply being appended to the release tarball).  Branches serve this purpose cleanly and as Stephen mentioned, could easily be ported to a different repository system in the future if needed.

--gary

On 2013-09-30, at 6:08 PM, Ariel Elkin <arielelkin at gmail.com> wrote:

> Nice work Steve!
> 
> I've been looking at the network view that GitHub provides and I find things pretty clear. 
> 
> It's a bit overkill to maintain a whole git branch ("releases") just for the purpose of providing STK users an easy way to download release tarballs. 
> 
> I think one single "master" branch suffices: carry out all the development work on it, create git tags on it to mark releases, and then direct end-users to the repository's Releases page that GitHub generates:
> https://github.com/radarsat1/stk/releases
> 
> Thus, end-users will only download the stable releases and not the latest upstream commits. 
> 
> If you take a closer look at the Releases workflow that's provided by GitHub, you might find how it can easily supersede the "releases" branch:
> https://github.com/blog/1547-release-your-software
> 
> Crucially for us, this Releases workflow enables us to attach assets to the source code release: these could be RtAudio and RtMidi, the empty Debug and Releases folders, and the makefiles? 
> 
> Ariel
> 
> On 30 Sep 2013, at 12:28am, Stephen Sinclair wrote:
> 
>> Hello all,
>> 
>> I have been working on my STK git repo, and I hope it is closer to
>> what might satisfy everyone.
>> 
>> The "master" branch is the main development branch.  It includes
>> purely source files such as "configure.ac", ".cpp" and ".h" files,
>> etc.  It does not contain the output of autoconf or doxygen, since
>> these are generated files.
>> 
>> The "releases" branch contains branches off of "master" for each
>> release.  In this branch, the generated "configure" and html
>> documentation are included.  For each "tarball" commit under
>> "releases", there is a tag associated.
>> 
>> This is illustrated in github's network view:
>> https://github.com/radarsat1/stk/network
>> 
>> The upshot is that there is a clear link to the development branch for
>> each release, and meanwhile if one browses to the github "releases"
>> page, which presents a download link for each tag in the repository,
>> one sees each release listed there:
>> 
>> https://github.com/radarsat1/stk/releases
>> 
>> If someone downloads 4.4.4, for example, they will get a file called
>> "stk-4.4.4.tar.gz", and he/she only needs to type "./configure &&
>> make" to build STK.
>> 
>> Meanwhile we can continue development in the "master" branch without
>> interference and history-confusing changes due to autoconf and
>> doxygen, etc.
>> 
>> A few decisions had to be made:
>> 1. what to do with the disappearing "Debug" and "Release" folders
>> 2. should "config.sub", "config.guess", and "install.sh" be included?
>> 3. remove any files that shouldn't have been in the release tarballs?
>> 
>> 1: I decided to add .placeholder files so that the Debug and Release
>> folders are there just as in the tarball releases.  As of commit
>> 8d2e9d9cf, which patches Makefile.in to create these directories if
>> they don't exist, the .placeholder files are removed.
>> 
>> 2. I wanted to remove these as they are part of autoconf/automake and
>> should be available on the developer's system, but in the end I found
>> that even after running "autoconf", the configure script would not run
>> correctly without these files present.  I left them in the repository,
>> but perhaps if we move to automake/libtool in the future it won't be
>> necessary to keep them.
>> 
>> 3. Any .o, *~, ._*, .DS_Store, etc.. files were removed before any
>> commit to the repository.  Same for a few Mach-O and ELF executables
>> that were in some release tarballs. (Mainly the projects/* folders)
>> 
>> So, still to deal with is how RtAudio and RtMidi should be handled.
>> i.e. as separate projects or what.. I'll leave that for a little
>> later, as it is after midnight now ;)
>> 
>> My inclination is to keep them in the same repository as STK but
>> generate different "tags" containing different subsets of the files
>> depending on which software is being released -- this could work
>> great, but has to potential to get a bit confusing -- though nothing
>> that we couldn't make easy with some simple scripting.  The
>> alternative is to have 3 separate repositories.  Then there's the
>> question of using git submodules or not.
>> 
>> Steve
>> 
>> _______________________________________________
>> Stk mailing list
>> Stk at ccrma.stanford.edu
>> http://ccrma-mail.stanford.edu/mailman/listinfo/stk
> 
> 
> _______________________________________________
> Stk mailing list
> Stk at ccrma.stanford.edu
> http://ccrma-mail.stanford.edu/mailman/listinfo/stk