Skip to content
This repository has been archived by the owner on Oct 21, 2022. It is now read-only.

Latest commit

 

History

History
105 lines (72 loc) · 7.21 KB

for-committers.md

File metadata and controls

105 lines (72 loc) · 7.21 KB
Raw

Dependencies

ClojureScript

Current ClojureScript version and libraries we use are in project.clj.

Notable JS dependencies

Node packages

Node package installs last done with node.js v2.5.0 and npm v2.13.2.

If you remove a Node package make sure to document that in the release notes, broadcast the change in the Gitter room, and post a topic about it in the Google Groups group. Plugins, including user plugins (i.e. plugins not listed in the official plugin list), might be using a package without including it in its own project.

Node dependencies are at deploy/core/node_modules/. This directory is currently a mix of vendored dependencies, forked dependencies and Light Table specific libraries:

  • Vendored dependencies are "dependencies" in package.json
    • These are dependencies that should not be modified and should be updated with upstream versions.
    • To update an individual dependency: cd deploy/core && npm install NAME@VERSION e.g. npm install [email protected].
    • To see outdated dependencies: npm outdated.
    • Dependencies should not be updated without good QA and checking the dependency's changelog.
  • Forked dependencies are "forkedDependencies" in package.json
    • These packages have had custom commits that should get sent upstream. These should eventually become vendored dependencies.
    • Some of them differ slightly from the original e.g. shelljs while others vary much more e.g. socket.io.
  • Light Table specific libraries
    • clojurescript - Provides cljsDeps.js
    • codemirror_addons - Provides codemirror addons
    • lighttable - Mostly lighttable js libs except for lighttable/util/{keyevents.js,throttle.js} which should be moved to vendored dependencies.

Electron

Allows us to build cross platfrom desktop apps. See Electron guide

Other

Running Light Table Code in Light Table

Generally, and unless you know what you're doing, do not eval entire files of the Light Table source; eval individual forms.

As Gabriel explains in this comment in issue #2170:

Depending on the file you're re-evaling, a whole file re-eval often redefines core LT object types and recreates LT objects. This can have dire consequences in some files e.g. re-evaling object.cljs will freeze LT as LT no longer has any objects defined. In the case of editor.cljs, if you comment the editor object type and do a file re-eval, you don't see errors. My suggestion is to stick to evaling forms when exploring LT and only do a file eval as you learn more of the codebase and understand the implications of a given file eval. I can add a brief description about this in the wiki or doc/for-committers.md if you think that'd be helpful to others.

Code Conventions

  • See the LightTable Style Guide.

Code Reading

When reading LT's source you may come across a fn that doesn't have an obvious use and may appear to be unused. Some tips to confirm how it is/was used:

  • Do a LightTable user search for the given fn. For example, to see where proc/exec is used
  • git log -u -S WORD will do a code history search for WORD

Upgrading ClojureScript

When upgrading ClojureScript, cljsDeps.js needs to be rebuilt with lein cljsbuild once cljsdeps. cljsDeps.js is used by threadworker.js to run javascript in a background thread. This background thread is invoked with the background macro.

Release process

Pre-release checklist:

  • Notify users (as described above in the Node packages section) if any Node.js packages have been removed as plugins may depend on them

This is our release checklist which can be dropped in to an issue:

  • Release 0.X.X - [ ] Version updates - [ ] Update deploy/core/package.json, deploy/core/version.json and project.clj to 0.X.X - [ ] Make sure electron version is up to date in version.json - [ ] Make sure plugin versions in script/build.sh are latest versions - [ ] Add changelog with notes for release (i.e release notes) to CHANGELOG.md - [ ] Each core developer should QA at least one OS using the QA checklist - [ ] When QA passes freeze master - [ ] Add changelog to GH release draft - [ ] Upload binaries from script/build.sh --release to draft. Don't forget to click Save draft! - [ ] Generate an MD5 checksum for the binary package: - [ ] Run certUtil -hashfile lighttable-x.y.z-windows.zip MD5 on Windows. - [ ] Run openssl md5 lighttable-x.y.z-mac.tar.gz on Mac OS X or Linux. - [ ] Publish GH release which creates git tag and notifies users about new release - [ ] Update download links on lighttable.com - [ ] Mailing list announcement - example email - [ ] Optional blog post if a major release - [ ] Inform Brian Dukes so that he can update the Chocolatey package - [ ] After release, build api documentation

Build API documentation

Run script/build-api-docs.sh on a clean git state to build API documentation for the current LT version and publish generated docs. Make sure there are no pending git changes as this script will change git branches and push generated API docs to gh-pages.

Expect to see a ton of warnings e.g. WARNING: Use of undeclared Var cljs.core/seq at line 197. This will be noise we have to live with until we upgrade ClojureScript.

To build documentation locally for debugging of documentation generation, run lein with-profile doc codox. This will create a codox directory within the LightTable directory. Do not include in pull requests or commits. Note, the generated documenation will not have styling, and the view source links may be incorrect.