Home

This is the internal dev corner of basil.js, probably not really interesting. For tutorials, examples and documentation go to the official website: http://basiljs.ch

Development Environment Setup (OS X)

• install Node.js (4.5 or higher) using one of these methods
• • Homebrew or creationix/nvm: Node Version Manager or from download Node.js (Download is not recommended. The changes in Node.js are so fast it makes sense to use some kind of package/version manager)
• Fork the GitHub repository to your account
• clone your repo git clone git@github.com:[YOUR USER NAME]/basil.js.git ~/Documents/basil/bundle
• Install the bundling dependencies

Run:

# cd into the bundle folder
# normally this is ~/Documents/basil/bundle
cd ~/Documents/basil/bundle
# install all the tools needed to bundle basil.js
npm install
# watch for changes in the ./src/ folder
npm run watch

• Install Sublime Text
• Install Sublime package sublime-jsdocs "DocBlockr"
• Install Sublime package SublimeLinter
• Install Sublime package SublimeLinter-eslint
• Install the Indesign Build Script in Sublime Text. Copy the folder Basiljs (bundle/extras/Sublime Text/Basiljs) to your Sublime Text 2 Packages directory e.g. OS X: ~/Library/Application Support/Sublime Text 2/Packages/Basiljs
• In Sublime go to Project -> Open Project... and select basil.sublime-project

Coding Conventions and Rules

basil.js uses "Code Conventions for the JavaScript Programming Language" by Douglas Crockford with these modifications:

• The unit of indentation is two spaces

Furthermore these structures turned out to be best practice in the basil.js source file:

Checking Primitives

• typeof var === 'undefined'
• typeof var === 'number'
• typeof var === 'string'
• typeof var === 'boolean'

For Complex Objects

• var instanceof PageItem
• var instanceof TextFrame
• var instanceof Function

or even better use our type util functions: isString(), isNumber(), isText() etc.

Adding new features/branches

To add a new feature on a new branch (from the command line) you should use the following commands.

# get the latest changes
git pull origin develop
# create a new branch
git branch my-new-feature
# change into that branch
git checkout my-new-feature
# edit the hell out of it.
# …
# …
# some time later
# if there is a new file add it to the index
git add my-file.js test/aweseome-feature-tests.js
# commit only the changed file
git commit my-file.js -m "added awesome feature"
# also commit the changelog
git commit changelog.txt -m "added infos to changelog"
# don't forget to commit the bundled basil.js file as well
git commit basil.js -m "bundled basil.js"
# if you added a test you also need to commit them
git commit test/aweseome-feature-tests.js test/all-test.js -m "added awesome tests" 
# you could commit all these files together, but it is easier to review 
# if you make a commit for each file
# push it to the remote
git push origin my-new-feature
# go back to the develop branch
git checkout develop
# wait for a review of other collaborators

Checklist for creating a Pull Request

• Create your PR against the develop branch. The master branch is used for releases only.
• If you change any files in src/includes, make sure to bundle a new basil.js file before committing by running npm run watch or npm run bundle.
• If you add or fix a feature, add it to changelog.txt
• If possible, add tests for new features or features with missing tests.

API Documentation

basil.js uses YUIDoc to document public API functionality. Installation and usage:

• Download and install Node.js
• Open up a terminal window and run "npm -g install yuidocjs"
• To generate the documetation in doc/api open up a terminal window and simply run "yuidoc ." in the basil.js project directory

Utf-8 Bom Commits Issues

don't create new files in extendscript! for some reason extendscript adds (sometimes) an utf-8 bom flag to files, which causes problems in github. if you have such a file you can "repair" it with the following terminal commands: vim file.jsx :set nobomb :wq

Git Snippets

How to create a tag

commit your changes, get the commit id e.g. 5e7ddab4f8, then add the tag with the following commands:

• create the tag git tag -a "0.21_private_beta_end_of_world" -m "private beta release" 76497cd600
• check the tag git log --oneline --decorate --graph
• commit the tag to the repo git push --tags

Hard reset to origin/master

• if working directory not clean: git stash
• git fetch --all
• git reset --hard origin/master
• if stashed: git stash pop (to reinsert last working state)

Review your changes before committing

to get a overview what you are actually commiting use:

git add -p

This will give you an interactive prompt to only commit the changes you really need. You can also just patch one file in the interactive prompt by running:

git add path/to/FILE.EXT -p

After that run

git commit -m "your message"

If you have something that you don't want to be added and you want your copy of Basil.js clean. Run this command after your commit:

git checkout -- .

It will reset everything to the latest commit.