Create a Best Practice submission template

[kfbishop]

[From Mobile RefArch for Mobile]
Each submission should cover the following:
• Problem - What is being decided or the issue that is being addressed.
• Assumptions - What is believed to be true about the context of the problem?
• Motivation - Why this decision is important.
• Alternatives - A list of options considered and explanations.
• Decision - The decision taken, possibly with references to related artifacts.
• Justification - Why the decision was made together with reference to any supporting principles and
explanations of deviations from compliance.

[kfbishop]

I've created a simple description page, and submission template. I think we need to provide a proper web form for submissions as the primary means, with a template download as the secondary for submitters who wish to put more thought into submissions. The submission "form" can have a file upload input for those users.

GitHub has an Issues API that we should be able to use to collect submissions for review. We'll need to ensure that users have pull access to do form submissions, so this may not be practical. Our only other option is to set up our own server to collect submissions.

Thoughts?

[csantanapr]

Why not follow github patterns?

• Send in a pull request and associate it with the issue.

1. Create the issue like you mentioned
2. They will just need to fork the repo
3. Create a new branch for topic/submission
4. When committing associate the commit with the issue # including one of the key words "fixex #234" or "closes #2324"
   http://stackoverflow.com/questions/1687262/link-to-github-issue-number-with-commit-message
5. Submit a pull request.

• All this can be done from command line or Github GUI

This way there are number of side benefits:

• People get more familiar with collaborations tools (i.e. git ot github)
• We keep discussion, inline comments, and so on in the github issue
• Attribution to authors: Contributions are associated with author.

[kfbishop]

I guess to me this depends on how much we want to expose "github" being central to the entire app and site. I agree with you that using standard github conventions make since, I'm concerned that it will drive off potential contributors. Do we want to force contributors to follow GIT concepts? Developers, sure. What about thought leaders in business, designers, etc. This would be all new and confusing. I'm leaning towards our site minimizing git as much as possible. I dont want to force constraints on us or contribs into strict conventions if its not focal to our mission.

[csantanapr]

I agree, but for folks that are advance and want to follow the flow. I was thinking on having more contributors help with the site and increase contributors.

What about giving options:

Option 1(Hacker):
Hacker and want to send a pull request with your markdown file into the site

Option 2 (Hacker Wannabe):
You mentioned that they already have to create a github issue, what about if they just copy paste the markdown content into the issue body?
Or copy and paste a public URL/link where we can get the content (google doc, other blog, dropbox, github, etc..)

Options 3 (What is a Hacker?):
Send an email with the file in markdown format using the template to: admin AT spajs.org

We can start with email and avoid the form for now.

If you think we still need the form submission I will try looking into a a Google Doc Form.
Maybe instead of sending a file the can submit a public url

I just want to avoid dealing with files, and if there are comments or reviews, the person needs to send us another files and so on.
Not sure if Google Doc Forms have upload file capability