When SVN was the “go to” version control system, I was the “Patch” manager for the project.
I was responsible for ensuring community provided patches, got “seen” by the project committers, and we kept a database, too of all submitted patches and their “status”…
I quite enjoyed it.
Anyway - I would like to volunteer for some work, to help Lucee out - since I use it for free and see a place where I could help out and that is with documentation.
I already have the information for submitting PRs for doc changes, which is great.
As usual - please forgive me if we already have my suggestion in place…
As an ongoing process - as opposed to adhoc doc changes;
How about if we (me) - Go through all the release notes for every new release,
And update the docs as required for the bugfix / enhancement.
As an extra, TAG me in any conversations where a documentation update is needed, for adhoc changes.
I’m always doing mini edits when looking at the docs and finding something missing / confusing etc
Same goes for exceptions, sometimes they are a bit confusing, so I’ll often fire off a PR (or commit directly these days as I’m somewhat more involved in the project than when I started doing this), you don’t need to raise a bug in jira. That includes grammar, upper casing the first word, etc etc.
any new functions / tags / args are automatically generated and added from the underlying definitions
Lucee docs are often ahead of the underlying definitions, as docs are generated from the latest stable release
We don’t have the ability to round trip docs edits back into the Lucee code base (yet) that’s why you’ll see with the interactive docs editor sometimes the source definition and the docs version
@Gavin_Baumanis that would be really great!!! Lucee needs way more contributions from us who are not Lucee devs!
Some issues are also so quickly done and updated just by using the githubs web interface. If you see a broken link or a typo, just click on the github link, edit it and PR it. You don’t need to run any fork locally.
I wonder why some users ping @Zackster on cfml slack for particular doc changes, writing a complete long thread about it, instead of just updating it right away on github. Sometimes the time of writing the slack thread would even consume more time than just editing the docs source right away. But at least we get all notified, which is good and at least that is a better help than not telling anything about an issue.
One thing that I have used for static code (and github pages) is Jekyll. I don’t particularly recommend it but might that be a bit better? I guess the issue we have is that with each version we update the docs too.
Despite being “open-source” - and talking just for myself - but I imagine it is similar to others;
“I” don’t want to step on anyone else’s toes,
“I” don’t know the process,
“I” want to humiliate myself, by doing something wrong (whatever that is), in a public space.
Anyway - I certainly understand, the effort required to write an email/post about what needs to be fixed - could have, instead, contributed a PR of the change they’d like to see implemented.
Just trying to use the commandBox version for documentation and I get the following error, which is strange to me - because it is in my home directory and I am an admin on my machine (windows)
C:\Users\gavin\commandBox\wwwroot\lucee-docs>box start name=luceedocslocalserver directory=C:\Users\gavin\commandBox\wwwroot\lucee-docs/server/ force=true rewritesEnable=true rewritesConfig=C:\Users\gavin\commandBox\wwwroot\lucee-docs/server/urlrewrite.xml port=4040 trayIcon=C:\Users\gavin\commandBox\wwwroot\lucee-docs/luceelogoicon.png heapSize=2048 cfengine="lucee@5"
× | Starting Server
| > C:\Windows\System32\server\server-luceedocslocalserver.json (Access is denied)
|------------------------------
ERROR (5.5.2+00578)
C:\Windows\System32\server\server-luceedocslocalserver.json (Access is denied)
caused by: java.io.FileNotFoundException
C:\Windows\System32\server\server-luceedocslocalserver.json (Access is denied)
\system\services\JSONService.cfc: line 435
433: fileSystemUtil.lockingFileWrite( path, newJSON );
434: } else {
435: fileWrite( path, newJSON );
436: }
437: }
called from \system\services\ServerService.cfc: line 2793
called from \system\services\ServerService.cfc: line 551
called from \system\modules_app\server-commands\commands\server\start.cfc: line 171
called from \system\services\CommandService.cfc: line 443
called from \system\services\CommandService.cfc: line 245
called from \system\Shell.cfc: line 816
called from \system\Bootstrap.cfm: line 119
Running the original powershell / cmd instance “As Administrator”, ensures it works correctly.