keighrim
commented
1 year ago My primary concern with https://github.com/clamsproject/apps/pull/41 is that it separates the user manual from the sdk repository, but there's chance of a SDK update causing changes in the app usability (even minor, like recent additional of multivalued runtime parameters). In such a case, SDK developers also need to update something that's now part of the SDK repository, and I don't like that fragmentation.
Here's one way to create an automatic synchronization mechanism;
- On SDK repo side, we keep the user manual up to date in the SDK repository (because SDK is the piece of software that determines the behaviors of apps, and thus the contents of the manual)
- On apps repo side, we use https://github.com/rolinh/jekyll-remote-markdown/ for automatic synchronization (this can only be done after https://github.com/clamsproject/apps/issues/42 is resolved)
- When there's a push to the SDK main branch that has changes in the user manual file, we manually invoke jekyll-build workflow on the apps repo side.
One problem is that once we set up a manual jekyll-build workflow, it will replace the default github pages workflow. Hence we need to carefully design the workflow to make sure the app registration workflow is not affected.
Because
(related to https://github.com/clamsproject/apps/issues/21)
There's a PR open in the app directory (https://github.com/clamsproject/apps/pull/41) that publishes the general app user manual as a webpage under the app-directory.
My reasoning behind the PR was that
sdk.clams.aiholds documentation for app developers, whileapps.clams.aiholds information for the app users.That said, the one that's included in the app scaffolding needs to be retired or synchronized.
Done when
CLAMS-generic-readme.mdfile is removed and instead add a link to the app user manual to the main readme .Or keep it as is and find a way to automatically synchronize its contents to https://apps.clams.ai/clamsapp .
Additional context
No response