You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+32-5Lines changed: 32 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,22 +9,49 @@
9
9
10
10
### Where can I find documentation about the JSON file format used?
11
11
12
-
It's documented in the [main README](/foundeo/cfdocs#json-file-documentation).
12
+
It's documented in the [main README](https://github.com/foundeo/cfdocs#json-file-documentation).
13
+
14
+
### How do I add a new tag or function
15
+
16
+
All of the tags and functions are defined in a JSON file located in the [data/en](https://github.com/foundeo/cfdocs/tree/master/data/en) folder.
17
+
18
+
1. Check the [data/en](https://github.com/foundeo/cfdocs/tree/master/data/en) folder to make sure no one else has already added it
19
+
2. Check the open [Pull Requests](https://github.com/foundeo/cfdocs/pulls) to make sure someone else has not already submitted it.
20
+
3. Create a new JSON file, take a look at an existing [function](https://github.com/foundeo/cfdocs/edit/master/data/en/arraylen.json) or [tag](https://github.com/foundeo/cfdocs/edit/master/data/en/cfcase.json) and use the [JSON format documentation](https://github.com/foundeo/cfdocs#json-file-documentation) for reference. Make sure there are links to official documentation (if there is no official documentation, explain this in the pull request comment)
21
+
4. Name it in all lowercase (eg `awesomefunction.json` or `cfawesome.json`)
22
+
5. Locate the new file in the [data/en](https://github.com/foundeo/cfdocs/tree/master/data/en) folder
23
+
6. Create a pull request
13
24
14
25
### What version of CF should the cfdocs CFML code work on?
15
26
16
-
It should run on Adobe ColdFusion 10+ or Lucee 4.5+ please make sure any changes
17
-
made to the codebase work on these platforms. Sadly that means you can't use member
18
-
functions at this time.
27
+
It should run on Adobe ColdFusion 2016+ or Lucee 5+ please make sure any changes
28
+
made to the codebase work on these platforms.
19
29
20
30
### Should I use tabs or spaces?
21
31
22
32
Tabs.
23
33
24
-
### For boolean values should I use `yes`/`no` or `true`/`false`
34
+
### For boolean values should I use `yes`/`no` or `true`/`false` or `1`/`0`?
25
35
26
36
Use `true`/`false`
27
37
38
+
### Should I use implicit or explicit notation for arrays and structs?
39
+
40
+
Example:
41
+
42
+
arr = []; // implicit
43
+
// is the same as
44
+
arr = arrayNew(1);
45
+
46
+
unorderedStruct = {};
47
+
orderedStruct = [:];
48
+
// is the same as
49
+
unorderedStruct = structNew();
50
+
orderedStruct = structNew('ordered');
51
+
52
+
53
+
Use implicit.
54
+
28
55
### How are my contributions licensed?
29
56
30
57
Please see the [LICENSE](https://github.com/foundeo/cfdocs/blob/master/LICENSE) file.
All of the tag and function documentation are defined in json files under [*data/en/functionname.json*](https://github.com/foundeo/cfdocs/tree/master/data/en)[function example](https://github.com/foundeo/cfdocs/blob/master/data/en/sessioninvalidate.json)[tag example](https://github.com/foundeo/cfdocs/blob/master/data/en/cfhtmltopdf.json).
12
+
All of the tag and function documentation are defined in JSON files under [*data/en/functionname.json*](https://github.com/foundeo/cfdocs/tree/master/data/en)[function example](https://github.com/foundeo/cfdocs/blob/master/data/en/sessioninvalidate.json)[tag example](https://github.com/foundeo/cfdocs/blob/master/data/en/cfhtmltopdf.json).
14
13
15
14
This makes the documentation super easy to edit and allows developers to run a local version of the site "out of the box" since no database setup is required.
16
15
@@ -22,46 +21,50 @@ This makes the documentation super easy to edit and allows developers to run a l
22
21
The cfdocs.org site can run locally very easily thanks to CommandBox.
23
22
24
23
1. Go download [CommandBox](https://www.ortussolutions.com/products/commandbox) if you do not have it already.
25
-
2. Download this repository and extract it to a folder, or clone it from this repository. If you are going to be making changes to the docs I would suggest you fork it, see Adam Tuttle's guide: [GitHub tip for your first pull request](https://adamtuttle.codes/your-first-github-pull-request/)
26
-
3. Run `box server start` from Command Prompt or Terminal in the root directory.
24
+
2. Download this repository and extract it to a folder, or clone it from this repository.
25
+
3. Make a copy of `.env.example` and name it `.env`. This contains required environment variables. [learn more](https://github.com/commandbox-modules/commandbox-dotenv)
26
+
4. Run `box server start` from Command Prompt or Terminal in the root directory.
27
27
28
28
CommandBox will start an embedded CFML server on port 8411, and you can browse to [http://localhost:8411/](http://localhost:8411/) to view the docs.
29
29
30
-
If you don't want to go the commandbox route you can simply download it and unzip it to a web root and try it out (requires CF10+ or Lucee 4.5+), but you will probably spend more time trying to get it working than the 1-2 minutes it will take to download and learn how to use commandbox.
30
+
If you don't want to go the CommandBox route you can simply download it and unzip it to a web root and try it out (requires CF10+ or Lucee 4.5+), but you will probably spend more time trying to get it working than the 1-2 minutes it will take to download and learn how to use CommandBox.
31
31
32
32
## How to contribute
33
33
34
+
If you are interested in contributing going I suggest you fork it, see Adam Tuttle's guide: [GitHub tip for your first pull request](https://adamtuttle.codes/blog/2014/your-first-github-pull-request/)
35
+
34
36
If you are interested in helping you can just copy a tag or function and write up some documentation. The documentation doesn't need to be super wordy and should not be a copy of Adobe's documentation word for word.
35
37
36
38
CFDocs.org is meant to be a quick reference so keep it short and sweet. E.g. attribute names / function arguments and one two sentence descriptions.
37
39
38
40
#### The easy way to edit the docs
39
41
40
-
1. Browse the [data/en/](https://github.com/foundeo/cfdocs/tree/master/data/en) folder of this repository on github and find the tag or function you want to edit.
42
+
1. Browse the [data/en/](https://github.com/foundeo/cfdocs/tree/master/data/en) folder of this repository on GitHub and find the tag or function you want to edit.
41
43
2. Click the edit button (pencil)
42
-
3. Commit / Send a pull request.
44
+
3. Commit
45
+
4. Send a pull request to merge your change with this repository.
43
46
44
47
#### The better way to edit the docs
45
48
46
-
1. fork the project to your GitHub account *need help? read this: [GitHub tip for your first pull request](http://fusiongrokker.com/post/github-tip-for-your-first-pull-request)*
49
+
1. fork the project to your GitHub account *need help? read this: [GitHub tip for your first pull request](https://adamtuttle.codes/blog/2014/your-first-github-pull-request/)*
47
50
2. clone it locally
48
51
3. make your changes
49
-
4. test it locally using commandbox (see above)
52
+
4. test it locally using CommandBox (see above)
50
53
4. once you are done you can send a pull request, and I'll merge it into the main repository.
51
54
52
55
### Not sure what you can contribute?
53
56
54
57
We need help expanding existing tag and function documentation. Look through the reference pages till you find one needing more definitions or examples. Also see:
@@ -72,14 +75,14 @@ We need help expanding existing tag and function documentation. Look through the
72
75
"function"
73
76
],
74
77
"description":"A short description that describes what the tag or function does.",
75
-
"discouraged":"Only add this key if this tag/function is discouraged by the community.",
78
+
"discouraged":"Only add this key if this tag/function is discouraged by the community. Displays a warning.",
76
79
"params":[
77
-
{"name":"funcArgNameOrTagAttributeName", "description":"What it does", "required":true, "default":"false", "type":"boolean", "values":["true", "false"]}
80
+
{"name":"funcArgNameOrTagAttributeName", "description":"What it does", "required":true, "default":"false", "type":"boolean", "values":[]}
78
81
],
79
82
"engines":{
80
83
"coldfusion":{"minimum_version":"10", "notes":"CF Specific Info Here", "docs":"http://learn.adobe.com/wiki/display/coldfusionen/function"},
81
-
"railo":{"minimum_version":"4.1", "notes":"Railo Specific Here", "docs":"http://railodocs.org/index.cfm/function/sessionrotate"},
82
-
"lucee":{"minimum_version":"4.5", "notes":"Lucee Specific Info Here", "docs":"http://docs.lucee.org/reference/functions/name.html"}
84
+
"lucee":{"minimum_version":"4.5", "notes":"Lucee Specific Info Here", "docs":"https://docs.lucee.org/reference/functions/name.html"},
85
+
"railo":{"minimum_version":"4.1", "notes":"Railo Specific Here", "docs":"http://railodocs.org/index.cfm/function/sessionrotate"}
83
86
},
84
87
"links":[
85
88
{
@@ -106,7 +109,7 @@ The name of the tag or function, use lowercase.
106
109
107
110
##### type
108
111
109
-
Either `function` or `tag` or `listing` a *listing* is how categories are made, they simply contain a `name`, `description`, and a list of `related`
112
+
Either `function` or `tag` or `listing` a *listing* is how categories are made, they simply contain a `name`, `description`, and a list of `related` items.
110
113
111
114
##### syntax
112
115
@@ -122,7 +125,7 @@ For functions, shows the available member function syntax.
122
125
123
126
##### returns
124
127
125
-
The returntype of a function.
128
+
The returntype of a function. Valid options are: `any`, `array`, `binary`, `boolean`, `date`, `function`, `guid`, `numeric`, `query`, `string`, `uuid`, `variableName`, `void`, `xml`. Default value is `void`.
126
129
127
130
##### related
128
131
@@ -152,7 +155,7 @@ Use this to link to blog entries or other useful related content.
152
155
153
156
Show example code. It is very helpful to readers to use the `result` to show the expected result of the code sample when applicable. This has to be JSON, so you can to do `\n` for newline, double quotes must be escaped `\"`. The `runnable` is a boolean that determines if the _Run Code_ button shows up next to the example.
154
157
155
-
We have an [example JSON utility](http://cfdocs.org/utilities/json/) that can be used to create the JSON by filling out a form.
158
+
We have an [example JSON utility](https://cfdocs.org/utilities/json/) that can be used to create the JSON by filling out a form.
156
159
157
160
Please see the [cfdocs contributor guide](CONTRIBUTING.md) for frequently asked questions.
0 commit comments