JavaScript Development Process

Code Style

Together with plone.api we developed Plone code style guidelines, which we are enforcing now for core Plone development.

This makes code so much more readable.

It currently does not cover JavaScript code guidelines, but those were considered when Mockup was developed.

And luckily, similar to PEP 8 and the associated tooling (pep8, pyflakes, flake8), JavaScript also has some guidelines - not official, but well respected.

Douglas Crockford - besides of specifying the JSON standard - wrote the well known book "JavaScript the good parts".

Out of that he developed the code linter JSLint.

Because this one was too strict, some other people wrote JSHint.

Todo

Mockup got an overhaul. The following content regarding JSHint is valid up to mockup 2.7.7. The link to .jshintrc configuration file is broken and needs to be updated. See plone/training#611

Mockup uses JSHint with the following .jshintrc configuration file:

{
   "bitwise": true,
   "curly": true,
   "eqeqeq": true,
   "immed": true,
   "latedef": true,
   "newcap": true,
   "noarg": true,
   "noempty": true,
   "nonew": true,
   "plusplus": true,
   "undef": true,
   "strict": true,
   "trailing": true,
   "browser": true,
   "evil": true,
   "globals": {
      "console": true,
      "it": true,
      "describe": true,
      "afterEach": true,
      "beforeEach": true,
      "define": false,
      "requirejs": true,
      "require": false,
      "tinymce": true,
      "document": false,
      "window": false
   }
}

Note

When working with JSHint or JSLint, it can be very useful to get some more context and explanation about several lint-errors. For JSHint there is a list of all configurable options: https://jshint.com/docs/options/

We strongly recommend to configure your editor of choice to do JavaScript code linting on save. The Mockup project is enforcing Lint-error-free code.

Besides of that, this will also make you a better coder. The JSHint site lists some editors with Plugins to support JSHint linting: https://jshint.com/install/

Regarding spaces/tabs and indentation:

• Spaces instead of tabs.

• Tab indentation: 2 characters (to save screen estate).

You have to configure your editor to respect these settings.

Confirming on a common code style makes contributing much more easier, friendly and fun!

Mockup Contributions

For each feature, create a branch and make pull-requests on GitHub.

Try to include all your changes in one commit only, so that our commit history stays clean.

Still, you can do many commits to not accidentally lose changes and still commit to the last commit by doing the following:

git commit --amend -am"my commit message".

Do not forget to also include a change log entry in the CHANGES.rst file.

Documentation

Besides documenting your changes in the CHANGES.rst file, also include user and developer documentation as appropriate.

For patterns, the user documentation is included in a comment in the header of the pattern file, as described in Writing Documentation For Mockup.

For function and methods, write an API documentation, following the apidocjs standard.

You can find some examples throughout the source code.

We also very welcome contributions to the training documentation and the official documentation.

As with other contributions: please create branches and make pull-requests!