Instructions how to send a draft #2

Open
opened 2022-12-02 14:44:29 -05:00 by Retropikzel · 8 comments
Owner

It would be nice to have clear instructions on the webpage how to participate. It currently says "Draft-based. Send a new draft whenever you have something people should read.". Whats a draft and where do I send it?

It would be nice to have clear instructions on the webpage how to participate. It currently says "Draft-based. Send a new draft whenever you have something people should read.". Whats a draft and where do I send it?
Owner

Absolutely. I wrote a "minimum viable" document at first since I wasn't sure if anyone would join yet :p

Absolutely. I wrote a "minimum viable" document at first since I wasn't sure if anyone would join yet :p
Owner

A draft is just like a SRFI draft. I.e. a git commit where the document and code are in a shape where you want people to take a(nother) look at it.

You can find git tags corresponding to each draft in every SRFI's repo. E.g. SRFI 207 has seven of them: draft-1 through draft-7. This has worked well.

The HTML document of each draft is pushed to the SRFI website. Whenever you click on a SRFI there, the site takes you to the latest draft of that SRFI. This has also worked naturally. (People rarely need to revisit old drafts, but they can be retrieved from git if needed.)

In between the draft commits there are ordinary git commits as the author works on the SRFI. These are not announced to readers, and the HTML is not uploaded to the SRFI website, but especially interested readers can follow these using git.

IMHO all of the above has worked very well and we should copy it.

A draft is just like a SRFI draft. I.e. a git commit where the document and code are in a shape where you want people to take a(nother) look at it. You can find git tags corresponding to each draft in every SRFI's repo. E.g. [SRFI 207](https://github.com/scheme-requests-for-implementation/srfi-207) has seven of them: `draft-1` through `draft-7`. This has worked well. The HTML document of each draft is pushed to the SRFI website. Whenever you click on a SRFI there, the site takes you to the latest draft of that SRFI. This has also worked naturally. (People rarely need to revisit old drafts, but they can be retrieved from git if needed.) In between the draft commits there are ordinary git commits as the author works on the SRFI. These are not announced to readers, and the HTML is not uploaded to the SRFI website, but especially interested readers can follow these using git. IMHO all of the above has worked very well and we should copy it.
Owner

As for where to send te draft...

SRFI has one person who is the Editor (for the last few years it's been Arthur). Drafts are sent to him.

We don't have an editor planned; I hope the process can operate by consensus. Just make a new git repo by following the example of the existing ones and I'll regenerate the front page.

As for where to send te draft... SRFI has one person who is the Editor (for the last few years it's been Arthur). Drafts are sent to him. We don't have an editor planned; I hope the process can operate by consensus. Just make a new git repo by following the example of the existing ones and I'll [regenerate the front page](https://gitea.scheme.org/groups/review).
Author
Owner

Absolutely. I wrote a "minimum viable" document at first since I wasn't sure if anyone would join yet :p

No worries. :) It will take me a while to have anything to present. I was just thinking from a position of a newcomer, which I am also in many ways. If we imagine someone lands on that web page and is interested it would be nice to have either the instructions or link to them on there. If the instructions are just here in the comments I dont think people will find them. I would have made a pull request to the website repo to save you the effort if I knew the "How To" myself.

I think since this process is more relaxed than SRFI it would make sense to make the participation process simple and guiding people is important for that.

> Absolutely. I wrote a "minimum viable" document at first since I wasn't sure if anyone would join yet :p No worries. :) It will take me a while to have anything to present. I was just thinking from a position of a newcomer, which I am also in many ways. If we imagine someone lands on that web page and is interested it would be nice to have either the instructions or link to them on there. If the instructions are just here in the comments I dont think people will find them. I would have made a pull request to the website repo to save you the effort if I knew the "How To" myself. I think since this process is more relaxed than SRFI it would make sense to make the participation process simple and guiding people is important for that.
Owner

Sure, take your time! It's going to be slow at first. If things go well, we'll start getting results (i.e. traffic and steadily improving proposals) in 6 months to a year.

The basic act that has to be done is to write a document.md to serve as the first draft. One of the regulars can then edit it so it conforms to the expected document structure, give it an ID number, and add it to the index.

It doesn't really matter how the Markdown file arrives.

  • The submitter could make a repo under their own Gitea account, which the regulars will clone under gitea.scheme.org/review.

  • Or upload it to a web server and send the URL.

  • Or send it by email.

Sure, take your time! It's going to be slow at first. If things go well, we'll start getting results (i.e. traffic and steadily improving proposals) in 6 months to a year. The basic act that has to be done is to write a `document.md` to serve as the first draft. One of the regulars can then edit it so it conforms to the expected document structure, give it an ID number, and add it to the index. It doesn't really matter how the Markdown file arrives. * The submitter could make a repo under their own Gitea account, which the regulars will clone under gitea.scheme.org/review. * Or upload it to a web server and send the URL. * Or send it by email.
Owner

But currently a Gitea account is required to comment on proposals, so the simplest way is probably that the submitter makes a repo which is cloned.

But currently a Gitea account is required to comment on proposals, so the simplest way is probably that the submitter makes a repo which is cloned.
Owner

How about these instructions, copied from srfi-discuss:

  • Create Gitea account.

  • Create a new issue at https://gitea.scheme.org/groups/review/issues and write your proposal into the issue using Markdown syntax.

  • One of the admins/regulars will turn your proposal into a new repo under the https://gitea.scheme.org/review organization.

  • Comments are made in the issue tracker of the proposal's repo.

  • You can make new drafts by cloning the repo and sending pull requests. (Just like in GitHub.)

How about these instructions, copied [from srfi-discuss](https://srfi-email.schemers.org/srfi-discuss/msg/21417377/): > - Create Gitea account. > > - Create a new issue at https://gitea.scheme.org/groups/review/issues and write your proposal into the issue using Markdown syntax. > > - One of the admins/regulars will turn your proposal into a new repo under the https://gitea.scheme.org/review organization. > > - Comments are made in the issue tracker of the proposal's repo. > > - You can make new drafts by cloning the repo and sending pull requests. (Just like in GitHub.)
Author
Owner

How about these instructions, copied from srfi-discuss:

  • Create Gitea account.

  • Create a new issue at https://gitea.scheme.org/groups/review/issues and write your proposal into the issue using Markdown syntax.

  • One of the admins/regulars will turn your proposal into a new repo under the https://gitea.scheme.org/review organization.

  • Comments are made in the issue tracker of the proposal's repo.

  • You can make new drafts by cloning the repo and sending pull requests. (Just like in GitHub.)

I would take out the last lines "(Just like in GitHub)" but otherwise it looks good.

> How about these instructions, copied [from srfi-discuss](https://srfi-email.schemers.org/srfi-discuss/msg/21417377/): > > > - Create Gitea account. > > > > - Create a new issue at https://gitea.scheme.org/groups/review/issues and write your proposal into the issue using Markdown syntax. > > > > - One of the admins/regulars will turn your proposal into a new repo under the https://gitea.scheme.org/review organization. > > > > - Comments are made in the issue tracker of the proposal's repo. > > > > - You can make new drafts by cloning the repo and sending pull requests. (Just like in GitHub.) I would take out the last lines "(Just like in GitHub)" but otherwise it looks good.
Sign in to join this conversation.
No Label
No Milestone
No project
No Assignees
2 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: review/2022-1#2
No description provided.