Embed code examples and tutorials in Kitura-Sample

[djones6]

Context & Description

Over time, Kitura and associated repositories have built up a multitude of code examples and tutorials. This presents an ongoing maintenance problem: when APIs or the Swift language itself change, these examples can get out of date, and may fail to compile.

Proposal

• Embed a copy of every code example and tutorial in Kitura-Sample
• Add comments to each example in Kitura-Sample with a link to the corresponding copy in the documentation
• Whenever a code example in Kitura-Sample requires updating, the documentation copy should be updated accordingly.

This is a significant task due to the number of code samples that currently are not represented in Kitura-Sample, however in the long term, it could mean that Kitura-Sample becomes the defacto place to prototype and test code samples, such that they are demonstrably correct at the point they are added to documentation.

Structuring the Kitura-Sample project

As there will be a large number of samples over time, we should consider the design of Kitura-Sample and how we would structure the project: for example, do we have separate targets for each 'feature' (optional repository) containing their code examples, and targets for each tutorial?

A benefit of separate targets would be that we can more accurately describe their dependencies so that, for example, the code for a single tutorial could be easily extracted as a standalone project.

Testing the samples

Consider whether we should add tests that exercise the code examples (may or may not be feasible, depending on whether they are complete enough to test).

What would an XCTest for a Kitura-Sample code example or tutorial look like?

Clear & Actionable Tasks

• Agree a layout / project structure for Kitura-Sample
• Strategy for testing code examples (XCTests?)
• Identify the list of repositories in IBM-Swift that contain code examples, which are appropriate to represent in Kitura-Sample
• Raise tasks for each repository to add the examples to the project, and confirm that they build and function correctly (tests added, if appropriate)

Exit Criteria:

This issue is complete once the following criteria are met:

• Design of Kitura-Sample and tests are documented
• Issues have been raised to cover each repo that needs adding to Kitura-Sample