mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2026-11-18 12:54:27 +00:00
Introduce coding style guidelines
This commit is contained in:
1 parent
e254529763
commit
a4f895dc4d
3 files changed
+45
-2
No files matched your search
+1
-1
@@ -1,3 +1,3 @@
|
||||
<h1 class=''>Contributing to <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki5.html'>TiddlyWiki5</a></h1><p><a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki5.html'>TiddlyWiki5</a> welcomes contributions to its code and documentation via <a class='tw-tiddlylink-external' href='https://github.com/Jermolene/TiddlyWiki5' target='_blank'>GitHub</a>. Please take a moment to read these notes to help make the process as smooth as possible.</p><h2 class=''><a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/GitHub.html'>GitHub</a> Issues</h2><p>We use <a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/GitHub.html'>GitHub</a> Issues to manage bug reports, feature requests for <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki.html'>TiddlyWiki</a>. To maintain their effectiveness we endeavour to have as few open issues as possible.</p><h3 class=''>Policies for Managing Issues</h3><p>Open issues must be actionable: generally either a reproducible bug report, or a specific feature request. From the perspective of the core developers, the issues list behaves like a shared todo list. Every item on the list requires a little bit of attention each time we check the list.</p><p><a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/GitHub.html'>GitHub</a> Issues are not very good for managing ideas that are not immediately actionable. Better to use the <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/Community.html'>TiddlyWiki discussion groups</a> for open ended questions, or speculative discussions of new features.</p><h3 class=''>Creating Issues</h3><p>When you do create an issue, remember that for effective debugging, we need as much information as possible. At a minimum, please try to include:</p><ul><li>A descriptive title</li><li>A summary</li><li>Steps to reproduce</li><li>Expected behaviour</li><li>Context (OS, browser etc.)</li></ul><p>Consider also adding screenshots if it makes things clearer.</p><p>There's a lot of good material on the web about bug reports:</p><ul><li><a class='tw-tiddlylink-external' href='http://mhay68.tumblr.com/post/1648223018/what-makes-a-good-bug-report' target='_blank'>http://mhay68.tumblr.com/post/1648223018/what-makes-a-good-bug-report</a></li><li><a class='tw-tiddlylink-external' href='http://www.chiark.greenend.org.uk/~sgtatham/bugs.html' target='_blank'>http://www.chiark.greenend.org.uk/~sgtatham/bugs.html</a></li></ul><h2 class=''>Contributor License Agreement</h2><p>Like other <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/OpenSource.html'>OpenSource</a> projects, <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki5.html'>TiddlyWiki5</a> needs a signed contributor license agreement from individual contributors. This is a legal agreement that allows contributors to assert that they own the copyright of their contribution, and that they agree to license it to the <a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/UnaMesa.html'>UnaMesa</a> Association (the legal entity that owns <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki.html'>TiddlyWiki</a> on behalf of the community).</p><ul><li>For individuals use: <a class='tw-tiddlylink-external' href='https://github.com/Jermolene/TiddlyWiki5/tree/master/licenses/cla-individual.md' target='_blank'>licenses/CLA-individual</a></li><li>For entities use: <a class='tw-tiddlylink-external' href='https://github.com/Jermolene/TiddlyWiki5/tree/master/licenses/cla-entity.md' target='_blank'>licenses/CLA-entity</a></li></ul><p><em>This is a first pass at a CLA for <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki.html'>TiddlyWiki</a>. Please let us know if we missed something important. If we do have to make essential changes to the CLA, there is a possibility that all contributors will need to sign it again</em></p><h3 class=''>How to sign the CLA</h3><p>Create a <a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/GitHub.html'>GitHub</a> pull request to add your name to <code>cla-individual.md</code> or <code>cla-entity.md</code>, with the date in the format (YYYY/MM/DD).</p><p>eg: <code>Jeremy Ruston, @Jermolene, 2011/11/22</code></p><p><strong>Thank you!</strong></p><h4 class=''>Attribution</h4><p>The CLA documents used for this project where created using <a class='tw-tiddlylink-external' href='http://www.harmonyagreements.org' target='_blank'>Harmony Project Templates</a>. "HA-CLA-I-LIST Version 1.0" for "CLA-individual" and "HA-CLA-E-LIST Version 1.0" for "CLA-entity"
|
||||
<h1 class=''>Contributing to <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki5.html'>TiddlyWiki5</a></h1><p><a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki5.html'>TiddlyWiki5</a> welcomes contributions to its code and documentation via <a class='tw-tiddlylink-external' href='https://github.com/Jermolene/TiddlyWiki5' target='_blank'>GitHub</a>. Please take a moment to read these notes to help make the process as smooth as possible.</p><h2 class=''>Coding Style</h2><p>Code contributions should follow the <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki%20Coding%20Style%20Guidelines.html'>TiddlyWiki Coding Style Guidelines</a>.</p><h2 class=''><a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/GitHub.html'>GitHub</a> Issues</h2><p>We use <a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/GitHub.html'>GitHub</a> Issues to manage bug reports, feature requests for <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki.html'>TiddlyWiki</a>. To maintain their effectiveness we endeavour to have as few open issues as possible.</p><h3 class=''>Policies for Managing Issues</h3><p>Open issues must be actionable: generally either a reproducible bug report, or a specific feature request. From the perspective of the core developers, the issues list behaves like a shared todo list. Every item on the list requires a little bit of attention each time we check the list.</p><p><a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/GitHub.html'>GitHub</a> Issues are not very good for managing ideas that are not immediately actionable. Better to use the <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/Community.html'>TiddlyWiki discussion groups</a> for open ended questions, or speculative discussions of new features.</p><h3 class=''>Creating Issues</h3><p>When you do create an issue, remember that for effective debugging, we need as much information as possible. At a minimum, please try to include:</p><ul><li>A descriptive title</li><li>A summary</li><li>Steps to reproduce</li><li>Expected behaviour</li><li>Context (OS, browser etc.)</li></ul><p>Consider also adding screenshots if it makes things clearer.</p><p>There's a lot of good material on the web about bug reports:</p><ul><li><a class='tw-tiddlylink-external' href='http://mhay68.tumblr.com/post/1648223018/what-makes-a-good-bug-report' target='_blank'>http://mhay68.tumblr.com/post/1648223018/what-makes-a-good-bug-report</a></li><li><a class='tw-tiddlylink-external' href='http://www.chiark.greenend.org.uk/~sgtatham/bugs.html' target='_blank'>http://www.chiark.greenend.org.uk/~sgtatham/bugs.html</a></li></ul><h2 class=''>Contributor License Agreement</h2><p>Like other <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/OpenSource.html'>OpenSource</a> projects, <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki5.html'>TiddlyWiki5</a> needs a signed contributor license agreement from individual contributors. This is a legal agreement that allows contributors to assert that they own the copyright of their contribution, and that they agree to license it to the <a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/UnaMesa.html'>UnaMesa</a> Association (the legal entity that owns <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki.html'>TiddlyWiki</a> on behalf of the community).</p><ul><li>For individuals use: <a class='tw-tiddlylink-external' href='https://github.com/Jermolene/TiddlyWiki5/tree/master/licenses/cla-individual.md' target='_blank'>licenses/CLA-individual</a></li><li>For entities use: <a class='tw-tiddlylink-external' href='https://github.com/Jermolene/TiddlyWiki5/tree/master/licenses/cla-entity.md' target='_blank'>licenses/CLA-entity</a></li></ul><p><em>This is a first pass at a CLA for <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki.html'>TiddlyWiki</a>. Please let us know if we missed something important. If we do have to make essential changes to the CLA, there is a possibility that all contributors will need to sign it again</em></p><h3 class=''>How to sign the CLA</h3><p>Create a <a class=' tw-tiddlylink tw-tiddlylink-missing' href='http://tiddlywiki.com/static/GitHub.html'>GitHub</a> pull request to add your name to <code>cla-individual.md</code> or <code>cla-entity.md</code>, with the date in the format (YYYY/MM/DD).</p><p>eg: <code>Jeremy Ruston, @Jermolene, 2011/11/22</code></p><p><strong>Thank you!</strong></p><h4 class=''>Attribution</h4><p>The CLA documents used for this project where created using <a class='tw-tiddlylink-external' href='http://www.harmonyagreemLine truncated
|
||||
</p><p><em>This file was automatically generated by <a class=' tw-tiddlylink tw-tiddlylink-resolves' href='http://tiddlywiki.com/static/TiddlyWiki5.html'>TiddlyWiki5</a></em>
|
||||
</p>
|
||||
@@ -1,11 +1,15 @@
|
||||
created: 20131101111400000
|
||||
modified: 20140110101537722
|
||||
modified: 20140112164329806
|
||||
tags: introduction
|
||||
title: Contributing
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
TiddlyWiki5 welcomes contributions to its code and documentation via [[GitHub|https://github.com/Jermolene/TiddlyWiki5]]. Please take a moment to read these notes to help make the process as smooth as possible.
|
||||
|
||||
!! Coding Style
|
||||
|
||||
Code contributions should follow the [[TiddlyWiki Coding Style Guidelines]].
|
||||
|
||||
!! GitHub Issues
|
||||
|
||||
We use GitHub Issues to manage bug reports, feature requests for TiddlyWiki. To maintain their effectiveness we endeavour to have as few open issues as possible.
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
title: TiddlyWiki Coding Style Guidelines
|
||||
tag: dev
|
||||
|
||||
! Motivation
|
||||
|
||||
TiddlyWiki is a large project with many interested parties. It benefits everyone if the code is as easy to read as possible. A key part of that it must be written and laid out consistently.
|
||||
|
||||
! Guidelines
|
||||
|
||||
!! Tabs and whitespace
|
||||
|
||||
TiddlyWiki uses 4-character tabs for indenting.
|
||||
|
||||
One blank line is used to separate blocks of code. Occasional blank lines are permitted within blocks for clarity, but should be avoided unless they solve a specific readability problem.
|
||||
|
||||
!! Layout of basic constructs
|
||||
|
||||
See the following example for layout of basic JavaScript constructs:
|
||||
|
||||
```
|
||||
/*
|
||||
Multiline comments are used to introduce a block of code such as a function definition
|
||||
*/
|
||||
function demoFunction(param,more) {
|
||||
// Proper sentence capitalisation for comments
|
||||
if(condition == "something") {
|
||||
// No space between "if" and the brackets; always spaces around operators
|
||||
myOtherFunction(one,two); // No whitespace within function parameters
|
||||
do {
|
||||
myCondition.explore(); // Always use semicolons
|
||||
} while(myCondition < worsens);
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
!! Strings
|
||||
|
||||
Double quotes are preferred over single quotes for string literals.
|
||||
Reference in new issue
Block a user