DEV Community

z0al
z0al

Posted on • Updated on

Submission friendly projects: The format

This is part 2 of a series of posts I'm planning to write while I'm building my open source side-project: Submitter. I'll be writing regularly(hopefully) about my work including all the challenges I came through.

Previous post: Submission friendly projects: Introduction

The Format

The core idea behind the project is to make submitting issues/PRs easier by rendering their templates in an interactive way. Below, I'm going to describe the things that I think could be improved when we render the template, your thoughts are welcome!

NOTE: The format should be compatible with GitHub Flavored Markdown specification.

Task Lists:

You can write task lists in GitHub like this:

- [x] something
- [ ] something else
Enter fullscreen mode Exit fullscreen mode

Or this:

* [x] something
* [ ] something else
Enter fullscreen mode Exit fullscreen mode

Or this:

+ [x] something
+ [ ] something else
Enter fullscreen mode Exit fullscreen mode

Or even as an ordered task list:

1. [x] something
2. [ ] something else
Enter fullscreen mode Exit fullscreen mode

Technically, the ordered lists are rendered as <ol> in HTML, but GitHub's stylesheet removes the numbers.

All of the above lists will produce the same output (checkboxes):

image

While rendering task lists as checkboxes are cool, sometimes it makes more sense to use radio buttons to render task lists, e.g:

I'm submitting: 

- [ ] A bug
- [ ] A feature request 
Enter fullscreen mode Exit fullscreen mode

But we need to determine how to write radio button lists. I'd prefer to use * to indicate radio button lists and use -,+, and numbers to indicate normal task lists. e.g:

* [ ] something
* [ ] something else
Enter fullscreen mode Exit fullscreen mode

Will be rendered as:

<input type="radio"> something </br>
<input type="radio"> something else </br>
Enter fullscreen mode Exit fullscreen mode

NOTE: because list item values may get so complex , we can't use dropdown (i.e. <select>) to render them as they may contain @mentions, #refs, links ...etc.

However, I'll need a markdown parser that provides the info of what character used as unordered list indicator (i.e. - or *)? However, all parsers I know don't! For that reason, I may find myself in a situation either to write my own markdown parser or use a different approach for example, ordered task list?

Markdown inputs

Rendering the issue/PR template as HTML makes it necessary to provide a way to insert markdown input. We will use the following pattern:

# Description

(description goes here)
Enter fullscreen mode Exit fullscreen mode

For the above example we will render a <textarea> (that has markdown support) as follows:

<h1>Description<h1>

<textarea placeholder="description goes here"></textarea>
Enter fullscreen mode Exit fullscreen mode

Later when the user submits the form, we will parse the input in the <textarea> as markdown and inject it in the final markdown document.

Of course, you can't use markdown ..etc between ( and ). If you want to tell the user something use normal markdown before the input pattern e.g:

# Description

Read this [guide]() to know how to write a good description.

(description goes here)
Enter fullscreen mode Exit fullscreen mode

Comments

Issue/PR template authors usually use HTML comments to guide you through the templates. But, because they're comments, they won't be visible when we render the template. A possible solution is to render them as <blockquote>s e.g:

<!-- use x instead of y -->
Enter fullscreen mode Exit fullscreen mode

Will be rendered to:

<blockquote>use x instead of y</blockquote>
Enter fullscreen mode Exit fullscreen mode

Show/hide sections

When using GitHub issues to report different types of issues i.e. bugs, feature requests, questions ..etc you may find there is type-specific information that isn't related to other types, for example, the version number isn't necessary for feature request issues.

In that case, a show/hide capability would be nice to have. However, I've no idea for now how to implement this feature, so I will ignore it for now and keep things simple. If you have an idea you'd like to share go ahead.

The stack

I will be using the following technologies/products to implement the project, I never used some of them, so it's a good chance to learn:

  • Auth0 for authentication
  • Koa for server-side logic
  • Next.js for server-side rendered React
  • Now for hosting.
  • And of course GitHub!

Edited: The project source code is available in ahmed-taj/submitter. It only contains initial setup right now!

More posts are coming!

Thank you :)

Top comments (2)

Collapse
 
marlysson profile image
Marlysson Silva

Great!!!
But will be a cli tool or a little web application?

Collapse
 
z0al profile image
z0al

A little web application for now

And yes! it could be a CLI too, but currently I've to focus on getting the initial release of the web version working. Then I may start the CLI