Add contribution guidelines #5
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| # Contributing to the Lua Users Foundation | ||
|
|
||
| This document serves as contribution guidelines and the points listed should be | ||
| followed for contributions to the foundation. | ||
|
|
||
| Contributions are expected to follow the [code of conduct](CODE_OF_CONDUCT.md). | ||
|
|
||
| ## Commit Guidelines | ||
|
|
||
| As is somewhat standard practice, the following should be observed: | ||
|
|
||
| - The usage of Markdown-formatted lists is allowed | ||
| - The header line should be no more than 60 characters | ||
| - Commit headers should start with an imperative verb, to act as a description | ||
| of what applying the commit would do: "If applied, this commit will..." | ||
| - Paragraphs should be broken with an empty line between | ||
| - Further lines after the header should be no more than 72 characters | ||
| - Further lines, if required, should contain detailed information on: | ||
| 1. Implications of the changes in the commit | ||
| 2. Reasons the changes are required | ||
|
|
||
| Commits relating to one file should follow these guidelines: | ||
|
|
||
| - The header line should contain the filename and a short description of what | ||
|
There was a problem hiding this comment. Still not sure if enforcing the filename is ideal? I'll let others comment on this. Ideally we should make this more simple I think There was a problem hiding this comment. It is hard to prepare release notes without this requirement. OTOH, we're not releasing software from this repo... |
||
| applying the patch will do, in the format of "If applied, this commit will..." | ||
| - The second line should be blank | ||
|
|
||
| Example commit message: | ||
|
|
||
| ```markdown | ||
| CONTRIBUTING.md: Establish guidelines for new commits | ||
|
|
||
| Implications of Changes: | ||
|
|
||
| - Could possibly make it harder for outsiders to contribute | ||
| - Could create bloatware in the repository data | ||
|
|
||
| Reasons for Changes: | ||
|
|
||
| - Creates a structure which can be used to avoid excessive comments | ||
| during the review process | ||
| ``` | ||
|
|
||
| Commits relating to multiple files should follow these guidelines: | ||
|
There was a problem hiding this comment. Kind of disagree we should treat commits using multiple files or single files differently. Looks like it could generate some inconsistency. Also I don't think there's any reason to have different max header length for these scenarios. There was a problem hiding this comment. I put a limit on max header length because GitHub itself even recommends that length, and will trim messages that it considers "too long". There was a problem hiding this comment. no yea, I'm completely ok with having a limit, my point is this limit being different for single file commits and multiple files commit. could be the same limit for both :) |
||
|
|
||
| - The header line should contain a short description of what applying the patch | ||
| will do, in the format of "If applied, this commit will..." | ||
| - The second line should be blank | ||
| - The third line should begin a list of changed files, with a header along the | ||
| lines of "Changed Files:" | ||
|
|
||
| Example commit message: | ||
|
|
||
| ```markdown | ||
| Apply changes to files as per guidelines | ||
|
|
||
| Changed Files: | ||
|
There was a problem hiding this comment. Why is this needed? Doesn't git itself provide this outside of the commit message? Secondly, most this repo will consist of documents, not code, I don't think we need to be very strict with the body of the message as long as the header is clear. Or that some description is provided somewhere, such as in the PR description. To be frank, I would rather have a longer description at the PR than at each commit. I know this is not great for git history, but we are heavily depending on github and not just git already anyway because of the issues. There was a problem hiding this comment. Doesn't GitHub auto-populate the PR with the contents of the commit? My goal here is to avoid someone finding a segment of documentation that was added however long ago, and having to look back for a closed PR instead of being able to look directly at the commit. There was a problem hiding this comment. I'm not sure if github does that? This PR has empty description There was a problem hiding this comment. As discussed on Slack, it puts the first line in as the title, and the rest of the lines - which in this case didn't exist - as the description. |
||
| - README.md | ||
| - CONTRIBUTING.md | ||
|
|
||
| Reasons for Changes: | ||
| - This is an example message, but anyways: The guidelines changed, so this | ||
| commit adapts the documents to follow the new guidelines as of 2018-03-14. | ||
| ``` | ||
|
|
||
|
|
||
| ## Document Design Guidelines | ||
|
|
||
| Contributions to documents for the repository should follow these guidelines: | ||
|
|
||
| - Lines should be no more than 80 characters | ||
|
There was a problem hiding this comment. Why? It makes the document harder to edit, imo. All text editors support text wrapping. There was a problem hiding this comment. Vim hard-wraps (at least in my case) all Git commits, and as discussed for the sole purpose of this pull-request, GitHub sucks at showing the context of a line. If someone types out a whole paragraph, sure, GitHub wraps it. However, you'll end up saying something along the lines of "four sentences in, there's a typo" rather than just commenting on one 80-character line. There was a problem hiding this comment. I second the 80 characters limit. Otherwise diffs get difficult to review. There was a problem hiding this comment. BTW, |
||
| - Documents should be written using standard Markdown (try to avoid using | ||
| GitHub flavoring) | ||
| - Documents should use relative URLs when linking to other documents | ||
| - Links should use the format of putting a link at the bottom of the page if a | ||
| line breaks 80 characters | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,14 +1,29 @@ | ||
| # Lua Users Foundation | ||
|
|
||
| This is the main repository where the Lua community can collaborate in order to | ||
| organise the foundation. | ||
|
|
||
| # What is the Lua Users Foundation | ||
|
|
||
| The Lua Users Foundation is an association of individuals in a modular umbrella | ||
| structure with the mission of supporting and promoting the Lua programming | ||
| language, its community and ecosystems. Please take check the current draft of | ||
| our Manifesto for more details, or even collaborate to its definition. You can | ||
| see our work in progress in the [Pull Requests][pull-requests] of this | ||
| repository. | ||
|
|
||
| # Who we are | ||
| The list of people involved with the foundation can be seen [here][gh-org]. | ||
| This list is currently being updated and also in the meantime there is a | ||
| [discussion][issue-1] on how to define membership of the foundation. | ||
|
|
||
| # Join us | ||
|
|
||
| Join us and collaborate in this initiave. The work will be conducted in this | ||
| repository and we are also chatting about it at Slack. Click here to join our | ||
| [Slack Channel][slack-channel]. | ||
|
|
||
| [pull-requests]: https://github.com/lua-users-foundation/foundation/pulls | ||
| [gh-org]: https://github.com/orgs/lua-users-foundation/people | ||
| [issue-1]: https://github.com/lua-users-foundation/foundation/issues/1 | ||
| [slack-channel]: https://join.slack.com/t/lua-users-foundation/shared_invite/enQtMzMwMDQ2MTcwNzU4LTg1YmU1ZDg0ZGY0MGY2OTdhZjQ0YzZmNjAzNzdhMTZjNTdkMDNkOWNmZDlkMmZiNWQ0M2ZlNWQ4MGI5YjUxNzQ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please drop this line until there is a content in that file. No point in confusing the reader with illusory complexity.