Split up the repository

[tstenner]

I already started this discussion on Slack and the responses were generally positive so here's the official proposal:

Currently, the source code for liblsl, all language bindings and all apps is in a single repository. As a consequence:

• the history is currently at 265MB
• it's impossible for CI systems to figure out which parts need to be rebuilt after a commit
• tags and # of commits since a tag are meaningless
• commit access is granted for everything

So I'd propose to:

• create a new LSL organization with repositories for at least liblsl, the language bindings and the apps. Further discussion is needed if the apps should also be split up or if a single repository for all/most apps would suffice
• Replace the folders in the big repository with git submodules, which are essentially pointers to commits in the other repositories. The same tree as today can be downloaded / updated with a single git command, but it's also possible to download / update only a needed subset or check out a single repository (e.g. liblsl and liblsl-Matlab)

Advantages:

• the CI could rebuild only what's needed, changing a file in the BrainAmp app wouldn't rebuild the python bindings
• the commit history contains only commits for this app / binding
• developers could get commit rights only for a specific app
• Better version numbers: liblsl could have a version number like 1.12+23-c0ffee, i.e liblsl 1.12 + 23 new commits, commit hash c0ffee
• Each Conda build recipe could have a link to the repository so we could put them in a separate repository / submit them to conda-forge. Calling conda build liblsl would then download only the liblsl repo, build it and create a distributable package

With git filter-branch the commit (and authorship) history is preserved and filtered to only contain commits actually touching the files in the repository, so nothing is lost (except for commit hashes to the former big repository).

[dmedine]

I am totally on board with splitting up the repository. Matthew suggested at one point that each app have it's on repository. I would agree that it makes more sense to house each one in its own submodule rather than have a grand repository for all the apps. The rub (also pointed out by Matthew) is how to host binaries. The ftp at SCCN is still viable, but I would say that it is far from a sustainable solution.

One thing I have been thinking about is how to set up 'out of tree' CMake builds to generate development projects for apps. As far as I can tell this isn't really possible yet without some kludging. This is something to consider when breaking up the apps folder. What I would like is to be able to hit one local CMake command and generate a BrainAmp (to take an example) project that can be built and debugged, etc. without having to copy Qt and LSL dependencies manually, but also be able to run a global cmake command to build everything I want to 'install' (which is already there). I was planning on working this out sometime this summer when work slows down a bit.

On 2/17/2018 12:59 PM, Tristan Stenner wrote:

I already started this discussion on Slack and the responses were generally positive so here's the official proposal:

Currently, the source code for liblsl, all language bindings and all apps is in a single repository. As a consequence:

• the history is currently at 265MB
• it's impossible for CI systems to figure out which parts need to be rebuilt after a commit
• tags and # of commits since a tag are meaningless
• commit access is granted for /everything/

So I'd propose to:

• create a new LSL organization with repositories for at least liblsl, the language bindings and the apps. Further discussion is needed if the apps should also be split up or if a single repository for all/most apps would suffice
• Replace the folders in the big repository with git submodules https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects, which are essentially pointers to commits in the other repositories. The same tree as today can be downloaded / updated with a single git command, but it's also possible to download / update only a needed subset or check out a single repository (e.g. |liblsl| and |liblsl-Matlab|)

Advantages:

• the CI could rebuild only what's needed, changing a file in the BrainAmp app wouldn't rebuild the python bindings
• the commit history contains only commits for this app / binding
• developers could get commit rights only for a specific app
• Better version numbers: liblsl could have a version number like |1.12+23-c0ffee|, i.e liblsl 1.12 + 23 new commits, commit hash c0ffee
• Each Conda build recipe could have a link to the repository so we could put them in a separate repository / submit them to conda-forge. Calling |conda build liblsl| would then download only the |liblsl| repo, build it and create a distributable package

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/sccn/labstreaminglayer/issues/273, or mute the thread https://github.com/notifications/unsubscribe-auth/ADch7nHDjktavRgrahLHLl49Preq8Goeks5tVr8EgaJpZM4SJSW_.

[tstenner]

I've created an organization and split the Apps and bindings, you can find it in the new super repo. When cloning it, you need to either do git clone --recurse-submodules git@github.com:labstreaminglayer/superrepo.git or do git submodule update --init --recursive afterwards. I'm still figuring out the last details with out of tree builds, but I'm making good progress

[tstenner]

The rub (also pointed out by Matthew) is how to host binaries.

See here. The CI systems could also upload the results as Github Releases, but managing the keys / auth tokens is a big hassle.

[dmedine]

Just wondering where you are at on this, though I see you are busy with LabRecorder at the moment. I am asking because I want to merge a couple of long-standing PRs (Alejandro's wearable sensing app and a less stale neuro-prax app). The question is how to merge them into the super-repo. I don't want to mess up any workflow that you have set up there.

[cboulay]

@dmedine It's mostly done and everything seems to work, but there's a lot of momentum with this repo so I think the migration is being done very slowly and organically. i.e., when I'm answering questions, I now point people to the new app-specific repos. But eventually we will have to pull the trigger and redirect this repo to github.com/labstreaminglayer/labstreaminglayer (i.e., the 'super repo').

Typically you shouldn't be merging anything directly into the super repo. This repo has almost no actual code in it and instead just points to other repos via submodules. It is the submodules that should be updated, then the super repo should be updated to point to the newest version of the submodule.

If you're working on a NEW app, that doesn't already have its own repo and isn't already pointed to in the super repo, then you'll need to create a new repository under github.com/labstreaminglayer ... and after it is working well standalone then it can be added as a submodule to the super repo.

If you like, for these pre-existing PRs, you can just merge the PR in this legacy repo, create an issue to migrate the app to the new repository locations, then Tristan or I can take it from there. It'll probably be Tristan because I don't know how he managed to split things off and migrate while maintaining the commit history. I'm good with submodules but that's a whole different level.

[dmedine]

Perfect. Thanks for the detailed reply.

On 6/20/2018 7:54 PM, Chadwick Boulay wrote:

@dmedine https://github.com/dmedine It's mostly done and everything seems to work, but there's a lot of momentum with this repo so I think the migration is being done very slowly and organically. i.e., when I'm answering questions, I now point people to the new app-specific repos. But eventually we will have to pull the trigger and redirect this repo to github.com/labstreaminglayer/labstreaminglayer (i.e., the 'super repo').

Typically you shouldn't be merging anything directly into the super repo. This repo has almost no actual code in it and instead just points to other repos via submodules. It is the submodules that should be updated, then the super repo should be updated to point to the newest version of the submodule.

If you're working on a NEW app, that doesn't already have its own repo and isn't already pointed to in the super repo, then you'll need to create a new repository under github.com/labstreaminglayer ... and after it is working well standalone then it can be added as a submodule to the super repo.

If you like, for these pre-existing PRs, you can just merge the PR in this legacy repo, create an issue to migrate the app to the new repository locations, then Tristan or I can take it from there. It'll probably be Tristan because I don't know how he managed to split things off and migrate while maintaining the commit history. I'm good with submodules but that's a whole different level.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-398840406, or mute the thread https://github.com/notifications/unsubscribe-auth/ADch7k9OZDdeDkSzubmbmvivctrW7SbAks5t-oxmgaJpZM4SJSW_.

[tstenner]

If you like, for these pre-existing PRs, you can just merge the PR in this legacy repo, create an issue to migrate the app to the new repository locations, then Tristan or I can take it from there. It'll probably be Tristan because I don't know how he managed to split things off and migrate while maintaining the commit history. I'm good with submodules but that's a whole different level.

There's some filter-branch magic involved and my history doesn't reach back far enough for me to figure out the details, but for a small number of commits I've been using git show <commit-id> to create a patch I can apply to the directory in the new repository (or vice versa).

I'm also considering splitting up the BrainProducts apps, because they don't share anything and having one repository for three apps makes some things more complicated than they need to be.

[dmedine]

There's some filter-branch magic involved and my history doesn't reach back far enough for me to figure out the details, but for a small number of commits I've been using |git show | to create a patch I can apply to the directory in the new repository (or vice versa).

Cool. Maybe we can go over this when we meet up in September. It will be easy to take 5 minutes when we are in the same room.

I'm also considering splitting up the BrainProducts apps, because they don't share anything and having one repository for three apps makes some things more complicated than they need to be.

That's fine with me. I don't know why Christian did it that way to begin with. The only thing is that in the future I would like to use the same class for talking to actiCHamp and LiveAmp (since the underlying library is identical now). Basicallly LiveAmp.c/h will become BPAmp.c/h and be used by both apps. So those two should probably stay together. It will look a little funny, but in terms of repo organization it will probably make the most sense moving forward.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-398851684, or mute the thread https://github.com/notifications/unsubscribe-auth/ADch7q9xEhh-DvbPJpRxdMXl0dgOinYWks5t-pUOgaJpZM4SJSW_.

[mgrivich]

The super repo should be deprecated and locked as soon as is feasible (not very slowly and organically). Right now we are in a forked situation, which will get increasingly ugly and confusing with time.

On 6/20/2018 10:54 AM, Chadwick Boulay wrote:

@dmedine https://github.com/dmedine It's mostly done and everything seems to work, but there's a lot of momentum with this repo so I think the migration is being done very slowly and organically. i.e., when I'm answering questions, I now point people to the new app-specific repos. But eventually we will have to pull the trigger and redirect this repo to github.com/labstreaminglayer/labstreaminglayer (i.e., the 'super repo').

Typically you shouldn't be merging anything directly into the super repo. This repo has almost no actual code in it and instead just points to other repos via submodules. It is the submodules that should be updated, then the super repo should be updated to point to the newest version of the submodule.

If you're working on a NEW app, that doesn't already have its own repo and isn't already pointed to in the super repo, then you'll need to create a new repository under github.com/labstreaminglayer ... and after it is working well standalone then it can be added as a submodule to the super repo.

If you like, for these pre-existing PRs, you can just merge the PR in this legacy repo, create an issue to migrate the app to the new repository locations, then Tristan or I can take it from there. It'll probably be Tristan because I don't know how he managed to split things off and migrate while maintaining the commit history. I'm good with submodules but that's a whole different level.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-398840406, or mute the thread https://github.com/notifications/unsubscribe-auth/AFC33ciVhvMQXR43ji1GqiB5pTfI3GIIks5t-oxmgaJpZM4SJSW_.

[dmedine]

Sorry, I don't know if I understand you properly, Matthew. Did you mean that we should deprecate the current repo and move to the super repo right away, or simply abandon the super repo. I thought you were in favor (or at least agnostic) to separating the apps from each other and the lib. I of course agree that having two is bad.

My two cents is that we should keep using the current repository until it is possible to move everything in one move, switch over entirely, confirm that everything is in order, and then replace the current repository with a nothing but a pointer to the super repo. The last three steps should be done very fast, but getting the move prepared can go slowly as long as it is understood that the current repo is /THE repo/ until the switch.

On 6/21/2018 1:14 AM, Matthew Grivich wrote:

The super repo should be deprecated and locked as soon as is feasible (not very slowly and organically). Right now we are in a forked situation, which will get increasingly ugly and confusing with time.

On 6/20/2018 10:54 AM, Chadwick Boulay wrote:

@dmedine https://github.com/dmedine It's mostly done and everything seems to work, but there's a lot of momentum with this repo so I think the migration is being done very slowly and organically. i.e., when I'm answering questions, I now point people to the new app-specific repos. But eventually we will have to pull the trigger and redirect this repo to github.com/labstreaminglayer/labstreaminglayer (i.e., the 'super repo').

Typically you shouldn't be merging anything directly into the super repo. This repo has almost no actual code in it and instead just points to other repos via submodules. It is the submodules that should be updated, then the super repo should be updated to point to the newest version of the submodule.

If you're working on a NEW app, that doesn't already have its own repo and isn't already pointed to in the super repo, then you'll need to create a new repository under github.com/labstreaminglayer ... and after it is working well standalone then it can be added as a submodule to the super repo.

If you like, for these pre-existing PRs, you can just merge the PR in this legacy repo, create an issue to migrate the app to the new repository locations, then Tristan or I can take it from there. It'll probably be Tristan because I don't know how he managed to split things off and migrate while maintaining the commit history. I'm good with submodules but that's a whole different level.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub

https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-398840406,

or mute the thread

https://github.com/notifications/unsubscribe-auth/AFC33ciVhvMQXR43ji1GqiB5pTfI3GIIks5t-oxmgaJpZM4SJSW_.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-398926444, or mute the thread https://github.com/notifications/unsubscribe-auth/ADch7jOBRTH_pTLtsIl4XVg14w17PO2Jks5t-tdEgaJpZM4SJSW_.

[mgrivich]

Sorry, I got confused by the jargon. Ignore my previous message. The repos are becoming a maze of twisty passages, all alike :/. The Legacy repo at https://github.com/sccn/labstreaminglayer is the one that needs to be locked as soon as feasible. Yes, I am in favor of splitting LSL and Apps into different repos. However, I would leave the LSL language bindings inside of the main (new) LSL repo (they are currently divided). I consider these to be core to LSL and will always be maintained by core developers.

The super repo at https://github.com/labstreaminglayer/labstreaminglayer is kind of awkward, and is sort of a one-to-one replacement for the mess that we are trying to fix. But I will tolerate it until we have a better project management page and volunteer to create it :/.

[dmedine]

I also agree that the language bindings should not be separated.

On 6/21/2018 10:45 PM, Matthew Grivich wrote:

Sorry, I got confused by the jargon. Ignore my previous message. The repos are becoming a maze of twisty passages, all alike :/. The Legacy repo at https://github.com/sccn/labstreaminglayer is the one that needs to be locked as soon as feasible. Yes, I am in favor of splitting LSL and Apps into different repos. However, I would leave the LSL language bindings inside of the main (new) LSL repo (they are currently divided). I consider these to be core to LSL and will always be maintained by core developers.

The super repo at https://github.com/labstreaminglayer/labstreaminglayer is kind of awkward, and is sort of a one-to-one replacement for the mess that we are trying to fix. But I will tolerate it until we have a better project management page and volunteer to create it :/.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-399237790, or mute the thread https://github.com/notifications/unsubscribe-auth/ADch7j-7xg9rcnKD5FthG_KjLrBm1cRKks5t_AXcgaJpZM4SJSW_.

[tstenner]

The language bindings should also be separated, because they profit the most from good CI coverage (e.g. 'does this commit break the python bindings on arm64 RHEL 6.2 python 2.6?') and having one CI configuration (download liblsl, install Python/C#-compiler/PHP, build the bindings, run an example script) for each language makes things considerably easier.

Also, commits, bug reports and pull requests are mostly for a single language binding so we shouldn't flood the pylsl bug tracker with yet another 'Matlab error: lslloadlib not found' bug report.

The core developers are maintaining all the language bindings, but the can be added to the labstreaminglayer organization so they have access to all repositories automatically. (Plus, there are certain affinities, e.g. you do most of the Java stuff).

[mgrivich]

What does the CI in CI coverage stand for?

On 6/22/2018 3:37 AM, Tristan Stenner wrote:

The language bindings should also be separated, because they profit the most from good CI coverage (e.g. 'does this commit break the python bindings on arm64 RHEL 6.2 python 2.6?') and having one CI configuration (download liblsl, install Python/C#-compiler/PHP, build the bindings, run an example script) for each language makes things considerably easier.

Also, commits, bug reports and pull requests are mostly for a single language binding so we shouldn't flood the pylsl bug tracker with yet another 'Matlab error: lslloadlib not found' bug report.

The core developers are maintaining all the language bindings, but the can be added to the labstreaminglayer organization so they have access to all repositories automatically. (Plus, there are certain affinities, e.g. you do most of the Java stuff).

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-399400480, or mute the thread https://github.com/notifications/unsubscribe-auth/AFC33Se45U8o4FLrGKeOyLwYop26WsI5ks5t_Mj0gaJpZM4SJSW_.

[dmedine]

CI = Continuous Integration, I believe.

To me this is a small point and more about look and feel than actual function. I will say that moving forward I hope not to have to rely on bug reports and issues pages in order to provide support (i.e. set up a forum and provide an FAQ) and that since very little actually changes in the core of liblsl (boost updates aside) the language bindings shouldn't break too often anyway.

However, since Tristan and Matthew are the ones doing the most work in this area, my opinion carries little weight compared with theirs :)

On 6/22/2018 3:07 PM, Matthew Grivich wrote:

What does the CI in CI coverage stand for?

On 6/22/2018 3:37 AM, Tristan Stenner wrote:

The language bindings should also be separated, because they profit the most from good CI coverage (e.g. 'does this commit break the python bindings on arm64 RHEL 6.2 python 2.6?') and having one CI configuration (download liblsl, install Python/C#-compiler/PHP, build the bindings, run an example script) for each language makes things considerably easier.

Also, commits, bug reports and pull requests are mostly for a single language binding so we shouldn't flood the pylsl bug tracker with yet another 'Matlab error: lslloadlib not found' bug report.

The core developers are maintaining all the language bindings, but the can be added to the labstreaminglayer organization so they have access to all repositories automatically. (Plus, there are certain affinities, e.g. you do most of the Java stuff).

— You are receiving this because you commented. Reply to this email directly, view it on GitHub

https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-399400480,

or mute the thread

https://github.com/notifications/unsubscribe-auth/AFC33Se45U8o4FLrGKeOyLwYop26WsI5ks5t_Mj0gaJpZM4SJSW_.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-399436277, or mute the thread https://github.com/notifications/unsubscribe-auth/ADch7gOjuHJUxmjshp0Pl3z_XPoRnRCYks5t_OwCgaJpZM4SJSW_.

[cboulay]

Off-topic, but: No forums or mailing lists please! Well, one exception, I would love for there to be a neurotech.stackexchange.com ... but for that to survive it needs to be used. This could happen quite easily if EEGLAB, fieldtrip, brainstorm, and a few companies got on board.

[tstenner]

CI = Continuous Integration, I believe. To me this is a small point and more about look and feel than actual function.

With VS2008-VS2017 on Windows, Linux (+arm7 for the Raspberry Pi?) OS X and Android (with its differing/difficult libstdc++ implementation) + old and new lslboost we have a lot of targeted platforms and I don't expect anyone to test changes on all of them (nor do I think it's sustainable for me as the Linux guy and Chadwick as the OS X guy to singlehandedly take care of it). With a reasonable CI coverage we can tell immediately if a PR breaks one of the major three platforms and test e.g. VS2008 with the old lslboost from a clean build within 3 minutes.

A CI configuration also ensures that it's possible to build everything without undocumented or manual steps so build problems can be avoided or more easily triaged.

Off-topic, but: No forums or mailing lists please! Well, one exception, I would love for there to be a neurotech.stackexchange.com ... but for that to survive it needs to be used.

For actual bug reports, a bug tracker beats a mailing list hands down. For support requests, I'd still prefer a bug tracker because most of them boil down to insufficient documentation, but a good mailing list (+public archive) is also fine.

[mgrivich]

When you speak of continuous integration configuration, how is this done, exactly? Have you already set it up, or is it something that you hope to implement?

You say that we can tell if VS2008's build is broken in three minutes, but that you are not doing the testing. How then, is the testing done?

[tstenner]

@mgrivich It's already set up. For Windows (and hopefully Linux soon) there's an config file that has all the build steps and a tiny HTML form with a bit of JavaScript magic so start a build with overwritten parameters (e.g. a different VS version, additional compiler flags, ...). After a successful build I can download the binaries or run tests (which don't exist yet. At the minimum there should be a small test case that creates an outlet, a corresponding inlet and exchanges a few samples). These builds are currently started manually, but the can be started on each commit or PR

[mgrivich]

Please add specific and detailed documentation to the relevant README.md files (in https://github.com/labstreaminglayer/labstreaminglayer) on how to use these new build processes. Right now, I can't really evaluate it because everything is spread out (those links are to yet another repository,(https://github.com/tstenner/labstreaminglayer)), half-baked, and undocumented.

On 6/23/2018 1:55 AM, Tristan Stenner wrote:

@mgrivich https://github.com/mgrivich It's already set up. For Windows (and hopefully Linux soon) there's an config file https://github.com/tstenner/labstreaminglayer/blob/master/appveyor.yml that has all the build steps and a tiny HTML form with a bit of JavaScript magic https://github.com/tstenner/labstreaminglayer/blob/master/ci_console.html so start a build with overwritten parameters (e.g. a different VS version, additional compiler flags, ...). After a successful build I can download the binaries or run tests (which don't exist yet. At the minimum there should be a small test case that creates an outlet, a corresponding inlet and exchanges a few samples). These builds are currently started manually, but the can be started on each commit or PR

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sccn/labstreaminglayer/issues/273#issuecomment-399654365, or mute the thread https://github.com/notifications/unsubscribe-auth/AFC33VBQ4cKTs4IrFVx11G9hBwj62Nyeks5t_gJrgaJpZM4SJSW_.

[tstenner]

Right now the CI builds run only when triggered manually (via ci_console.html in your local repository), but I could enable them on each commit / PR so no manual intervention is required (unless you want to build with special flags).

Since updating the documentation get forgotten easily, I've started an example app that should demonstrate good practices. In each file, there's the code and special comments (prefixed with :) so a simple script can generate a folder newcomers can copy to start an app and a folder with the annotated, formatted code. I've just annotated the sample AppVeyor config and the sample Travis config.

In any case, we should decide where the documentation makes the most sense - right now, there are instructions in the Github wiki and various README files everywhere in the repository.

[mgrivich]

In any case, we should decide where the documentation makes the most sense - right now, there are instructions in the Github wiki and various README files everywhere in the repository.

Build instructions (or a link to build instructions) should be in the appropriate README files. https://github.com/labstreaminglayer/liblsl/blob/master/README.txt for liblsl, https://github.com/labstreaminglayer/App-BrainProducts/README.txt for App-BrainProducts etc.

These automatically appear below the source in github.

For an example of the level I'm looking for, see https://github.com/labstreaminglayer/liblsl-Java/blob/master/README.txt (which I wrote) or https://github.com/labstreaminglayer/App-LabRecorder/blob/master/readme.txt (which I didn't write).

The contents of the https://github.com/labstreaminglayer/labstreaminglayer/wiki should be moved to the appropriate repo's README for each of the apps.

Wiki documentation should only be for general reference information, like https://github.com/labstreaminglayer/labstreaminglayer/wiki/TimeSynchronization or big picture questions, like general tutorials.

Basically, the documentation should be clear, up-to-date, and in the first place that most people would look for it.

Since updating the documentation get forgotten easily

The solution for this is not to stop documenting, but to do a better job of updating the documentation. If a developer doesn't have time to update the documentation (and test, as long as we are being pedantic), that developer does not have time to touch the code.

You may wonder why I'm pushing documentation so hard. I know you have done a lot of work on this. However, without documentation that other people to easily follow what you did, we either have to redo your work (at unnecessarily high cost) or just not bother (which is what will happen for most of our users), and much of your work will be wasted.

[tstenner]

Build instructions (or a link to build instructions) should be in the appropriate README files. https://github.com/labstreaminglayer/liblsl/blob/master/README.txt for liblsl, https://github.com/labstreaminglayer/App-BrainProducts/README.txt for App-BrainProducts etc. These automatically appear below the source in github.

Github also renders Markdown files so I'd rather put it in a separate file (BUILD.md?). The documentation should target developers ("How do I build it? Which prerequisites do I need?") and end users ("What does this do? Where can I download XY? How do I use it?"), and developers will be more accustomed to reading separate build instructions.

The build instructions for all the apps I've touched are essentially the same:

• download or build liblsl
• mkdir build; cd build
• cmake -DLSL_INSTALL_ROOT=path/to/lsl ..
• cmake --build . --target install

Depending on the app there's also the issue of installing Qt and Boost, so for these it'd make more sense to have one central documentation how to install Qt, Boost and liblsl and specific instructions for this one app.

The contents of the https://github.com/labstreaminglayer/labstreaminglayer/wiki should be moved to the appropriate repo's README for each of the apps.

After they are updated. The LabRecorder documentation was still for the Python version on Google Code, but it's a great overview for end users. I've touched it up and moved the build instructions to a separate BUILD.md#

The solution for this is not to stop documenting, but to do a better job of updating the documentation. If a developer doesn't have time to update the documentation (and test, as long as we are being pedantic), that developer does not have time to touch the code.

But updating the documentation shouldn't involve finding out which of the three disagreeing files / wiki pages is the right one and rewriting it to reflect the state before the proposed change. The first step to keeping it up to date after changes is already having an up to date documentation.

My approach for this looks like this:

• have a single working CMake setup for liblsl, LabRecorder and the Examples with (pseudo-) automatic CI builds and binary upload somewhere. This is already at a "works-for-me-on-4-different-PCs"-level, perhaps @cboulay can chime in how well it works for him.
• provide an app template with documentation explaining each decision and common questions so the existing apps can easily adopt the build system / CI configuration / documentation and new apps already start at a well-documented state that's easy to update
• Provide a rough documentation, remove the remaining roadblocks I didn't see because of different setups (that's where e.g. @dmedine comes in)
• update the documentation with the feedback
• document the CI-configuration and deployment somewhere as soon as a decision's been made which services get actually used

You may wonder why I'm pushing documentation so hard.

It seems to me the our difference isn't in how important the documentation is but rather the details like the structure, the target audience and the approach (iterative/feedback driven vs. writing down everything at once). I'm looking forward to have one everything set up and documentated so it's easy for old timers and newcomers alike to work on this project :-)

[mgrivich]

Build.md instead of readme.md is fine.

Thanks for updating the LabRecorder documentation.

I'm looking forward to have one everything set up and documentated so it's easy for old timers and newcomers alike to work on this project :-)

Good.

Ideally, things should be buttoned up before the conference in September. Nothing like a deadline to focus the mind, and talks and training will go much smoother if we can point to a clean and functional repository (or collection of repositories). Will you be at the conference, by the way?

[tstenner]

Ideally, things should be buttoned up before the conference in September. Nothing like a deadline to focus the mind, and talks and training will go much smoother if we can point to a clean and functional repository (or collection of repositories). Will you be at the conference, by the way?

Of course, even if it takes me almost 3 hours to get there :-)

I've create a bug report in the new repository so this issue doesn't get too sidetracked