Publishing the cookbook

[lassik]

@jcubic Should we store the recipes as Markdown files in Git, and write some Scheme code to turn them into HTML and upload them on the server?

We should also decide on the URL - cookbook.scheme.org or doc.scheme.org/cookbook?

[jcubic]

I think this is a good idea, I can create some script to generate those markdown files. We can keep those scripts in a repo and update the files. I'll create something in a weekend. We will need to update the issues so the best solutions are in the main issue and not in the comments. Because I will generate the files from them.

There are out-of-the-box solutions for generating documentation, I will check if anything can be used. I like Jekyll for my projects it uses markdown files as a base I will check if there are any templates that could be used without any extra work. I think it will be lot easier even to create Jekyll site from scratch then to write scheme code, unless you know any framework/library that can help with this.

[jcubic]

We can also generate those markdown files on the fly and from them generate HTML and then upload them to the server.

[lassik]

Moving finished recipes from issues into .md files in the repo would be ideal, since the repo keeps Git history, whereas there's no standardized history for a GitHub issue; if the repo is ever moved from GitHub, we risk losing the issues. It's also easier to write scripts to work on files that exist directly in the repo.

Chicken Scheme has a Markdown parser that we are using to generate the www.scheme.org front page.

[APIPLM]

Moving finished recipes from the issues into markdown file is a good idea for publishing the cookbook. But the thing is that the recipes in the issue list have different form, let us say, with label help wanted issues. the solution is in the comments. And some of the recipes have option solutions in the comments, those solutions are needed to check by the requestor. Sound like we need a process to do that

1. Check the issue was requested with Recipe template
2. Toggle on the best solution for label help wanted Recipe issue.
3. Flag the option solution.

The problem is that those comments just mark the solution as the code. there is not a way for us to tag them as we need to for our purpose to generate into the output html with special tag in the html cookbook.

[lassik]

We could also use pull requests instead of issues to add the problems and solutions.

• To add a new problem, submit a PR that adds a new .md file with the problem description.
• To add a new solution, submit a PR that adds text to an existing .md file.

[lassik]

That way we would automatically get a Git history of all the edits to the cookbook, with the author of each edit clearly marked in Git, and we wouldn't have to manually copy text from issues to .md files.

[APIPLM]

Okay. Like create a draft version .md files of cookbook based on the discussion in the issue list. Then have pull requests to revise the .md file cookbook with the history in the Git. Issue and comments is a separate thing.

[lassik]

Yes. For new problems, we could have the discussion in the PR itself.

[lassik]

@jcubic What do you think about using PRs instead of issues to add/edit the cookbook?

[jcubic]

I'm fine but it's easier to add issue than the PR that requires a fork.

[APIPLM]

As discussing in the above. the issue template along with comments of the issue list may have a rework for the final cookbook. If we checked the output md files in the recipes folder of this repo, there is a few md files do not like what it supposed to be.For instance, split-a-string.md file does not have the content of the solution. The recipes with tag "help wanted" does not have the solutions section in these md files, which are format-a-unix-timestamp.md , find-all-matching-files-in-a-directory-tree.md , and removing-duplicates-from-a-list.md files. all of the solutions are in each of the issue comments.
I saw that repo was built its cookbook in the wiki of github, which can trace the change of the cookbook. It like host the documents in sub repo of the document project.

[jcubic]

We need to decide if we want to keep using issues that are simpler and easier for users (no need to fork) or go with PR.
If we will go with issues we can mark completed issues with a label. and generate files only for issues that have this label.
The problem with PR is that the user has to create a solution. With an issue anyone can just create a common problem and others may reply with the solution.

[APIPLM]

Yes. In the issue with comments it is about coming to comments section to find out which is the solution of the recipe issue by getting the body of https://api.github.com/repos/schemedoc/cookbook/issues/comments with completed issues as a label. But generate the process, do not know which one is, because of all of comments is marked the code as the same. So which one is the better solution, still is needed the providers to verified again as there are two solutions for one problem.The PR need to be forked ,and then merge. As I used to work on one document in the wiki for a project, that time the web version of wiki, is like online version of editor, when you login to the wiki page, active the page you edit. you can edit the page with the edit history, and one of your team come to edit the same page will see the edit history, and as well his editor history will be available for other member in the team.It like google online document.

[APIPLM]

So my suggestion is that collecting the problems by the issue template. Then come to PR to edit it and verify the solution with the providers as we have multiple solutions for one problem.Then finalize them. Make sure that all of the problems and the corresponding solutions come the final cookbook with the raiser of the issue and the provider of the solution.

[jcubic]

That is also a good idea, PR can be added for each Issue.

[lassik]

How about:

• Collect problems (questions) with issues
• Collect solutions (answers) with PRs

The first solution to a problem:

• Creates a new .md file for the problem.
• Closes the issue.

More solutions to the same problem, append and/or edit the existing .md file.

Opening a PR for each solution, means that anyone writing a solution needs to fork the repo, but that's doesn't take more time than writing the code, and then we'd get a git log of all new solutions, and edits to existing solutions.

[lassik]

If we will go with issues we can mark completed issues with a label. and generate files only for issues that have this label.

We can close the completed issues, and the issue->.md script can browse only the open issues.

[jcubic]

I think that I've didn't added to the script if issue is open or not.

The original idea for the issue was that they are simpler. But I've just realized that if someone has a GitHub account, that is required for creating issues and commenting, then he can just create a PR. That is not a problem. Also, we will encourage code contribution. We can keep issues with problem and code always need to be in PR, in that case, we will not need to create .md files from issues. If someone has a GitHub account he probably knows how to create a PR, and we can tag issues and PR with hash tags. like #11 (GitHub will automatically connect them). One more favor for PR is that they look nice in people's profiles.

[jcubic]

We will only need to update CONTRIBUTING.md and maybe create sample.md file that will be linked in CONTRIBUTING file. Also, update the issue template to include only a problem. With the info that code needs to be added in PR.

We can also create PR template where user need to check if he done what is required.

[jcubic]

If the cookbook site is ready on the staging website (server/ftp/ssh) then we can set up Github actions to upload the files automatically to the server. But I'm not sure about Scheme availability in GitHub actions, I'm not exactly sure how they work. But I would like to try them out.

[lassik]

The Chicken Scheme mailing list is very active. I'll ask them if they have tried running Chicken in GitHub actions.

For uploading the files, we are simply using rsync, with SSH public key authentication (we don't use passwords). If GitHub Actions can generate an SSH key-pair for itself, then we can add the public key from that pair to the server, and it will be easy to run rsync from Actions.

[lassik]

Wait, here it is: https://github.com/guenchi/setup-scheme

[lassik]

The GitHub API gives only open issues (not closed issues) with this syntax: https://api.github.com/repos/$user/$repo/issues?state=open

...but if we use only PRs, we don't need it.