Extract Samples into separate repository/repositories

[0Grit]

Our goal is to enable developers to trust our IoT clients and services so they can focus on the application specific detail of their work.

Their applications depend on the client not the other way around. Therefore I propose we pull out the samples directory into either it's own repository or multiple repositories. (1 per example)

The samples can then act as a working template for the developer to start from and eventually fork.

[mniestroj]

I agree with idea of creating application template(s). If feasible, I would try to reduce that to 1-2 application repositories.

However I would still recommend keeping most samples as part of this repository, because:

• maintaining single repository is much easier and takes less effort than maintaining >10 repositories, each for a single and simple sample application,
• as a developer I usually look for examples/ samples/ and tests/ directories in git repository that I have just downloaded, for code that solves a use case that I would like to cover in my application; I usually run grep inside such subdirectory and hence I am able to quickly find (or not) a sample code; downloading multiple repositories is very inefficient for users with similar expectations,
• building all samples as part of CI is much easier if they are all part of single repository,
• refactoring code that requires both client library and application changes is much easier (takes less time) within single repo.

[0Grit]

Then maybe we just give end to end examples their own repositories?

[beriberikix]

Then maybe we just give end to end examples their own repositories? 💯 on board with that!

[0Grit]

@ChrisGammell @alvarowolfx sounds related to recent slack discussions.

[vitprajzler]

Haven't we already gone through this in the separate sample repository?

I share Marcin's concern about maintainability. I don't want to create a maintenance burden while the team is still quite small.

I'd say the dedicated repository for all samples would be a good compromise between maintainability and improved developer experience.

@mniestroj, could you help me understand what the maintenance effort would be for the single dedicated repository with samples?

[mniestroj]

Some related work/issues with splitting all samples into separate repository:

• No way to trigger basic build/runtime tests from SDK repo, as all the code that would use provided APIs would be in separate repo. One way to workaround that would be to make SDK depend on samples when doing CI. Not sure this is a good idea. Question is which revision of samples would be used when trying to test SDK changes.
• There are twice as much commits for changes that affect both repositories.
• As both repositories (SDK and samples) need to be in sync, one needs to explicitly reference revision of the other. This will result in dummy commit messages which just change revision abcdefg to bcdefgh.

Let's start with benefits of splitting samples into separate repository, as I don't see any of those. Having a separate template or reference application repository (like https://github.com/golioth/app-hello-golioth) that uses SDK makes perfect sense, but what we have inside samples/ right now are just very basic API usage examples, so that potential user does not have to search through another repo(s) in order to roughly evaluate those.

[0Grit]

I now see the purpose of the samples inside of our SDK as a very narrow scope way to show individual functionality in close proximity to the sources.

My original intent in this issue was not tuned to that fact and cast a net over all the samples. Thank @mniestroj thank you for guiding me to this understanding. It can now be closed.