Skip to content

Commit b67fbf7

Browse files
agjohnsonagjohnson
authored
Add development standards document to our documentation (#5808)
* Add development standards document to our documentation This document describes how core team should do development on RTD. * Fix typos and add placeholder for celery and database barrier * Update docs/development/standards.rst * Apply suggestions from code review * Make psql more optional, add celery debugging * Fix docs
1 parent 5bdb2f8 commit b67fbf7

File tree

3 files changed

+262
-158
lines changed

3 files changed

+262
-158
lines changed

‎docs/contribute.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,12 +117,13 @@ for your own :doc:`custom installation <custom_installs/index>`.
117117
:maxdepth: 1
118118

119119
development/install
120+
development/standards
120121
development/search
121122
development/architecture
122123
development/tests
123124
development/docs
125+
development/front-end
124126
development/design/index
125-
development/standards
126127
development/buildenvironments
127128
development/symlinks
128129
development/settings

‎docs/development/front-end.rst

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
Front End Development
2+
=====================
3+
4+
Background
5+
----------
6+
7+
.. note::
8+
9+
Consider this the canonical resource for contributing Javascript and CSS. We
10+
are currently in the process of modernizing our front end development
11+
procedures. You will see a lot of different styles around the code base for
12+
front end JavaScript and CSS.
13+
14+
Our modern front end development stack includes the following tools:
15+
16+
* `Gulp`_
17+
* `Bower`_
18+
* `Browserify`_
19+
* `Debowerify`_
20+
* And soon, `LESS`_
21+
22+
We use the following libraries:
23+
24+
* `Knockout`_
25+
* `jQuery`_
26+
* Several jQuery plugins
27+
28+
Previously, JavaScript development has been done in monolithic files or inside
29+
templates. jQuery was added as a global object via an include in the base
30+
template to an external source. There are no standards currently to JavaScript
31+
libraries, this aims to solve that.
32+
33+
The requirements for modernizing our front end code are:
34+
35+
* Code should be modular and testable. One-off chunks of JavaScript in templates
36+
or in large monolithic files are not easily testable. We currently have no
37+
JavaScript tests.
38+
* Reduce code duplication.
39+
* Easy JavaScript dependency management.
40+
41+
Modularizing code with `Browserify`_ is a good first step. In this development
42+
workflow, major dependencies commonly used across JavaScript includes are
43+
installed with `Bower`_ for testing, and vendorized as standalone libraries via
44+
`Gulp`_ and `Browserify`_. This way, we can easily test our JavaScript libraries
45+
against jQuery/etc, and have the flexibility of modularizing our code. See
46+
`JavaScript Bundles`_ for more information on what and how we are bundling.
47+
48+
To ease deployment and contributions, bundled JavaScript is checked into the
49+
repository for now. This ensures new contributors don't need an additional front
50+
end stack just for making changes to our Python code base. In the future, this
51+
may change, so that assets are compiled before deployment, however as our front
52+
end assets are in a state of flux, it's easier to keep absolute sources checked
53+
in.
54+
55+
Getting Started
56+
---------------
57+
58+
You will need a working version of Node and NPM to get started. We won't cover
59+
that here, as it varies from platform to platform.
60+
61+
To install these tools and dependencies::
62+
63+
npm install
64+
65+
Next, install front end dependencies::
66+
67+
bower install
68+
69+
The sources for our bundles are found in the per-application path
70+
``static-src``, which has the same directory structure as ``static``. Files in
71+
``static-src`` are compiled to ``static`` for static file collection in Django.
72+
Don't edit files in ``static`` directly, unless you are sure there isn't a
73+
source file that will compile over your changes.
74+
75+
To test changes while developing, which will watch source files for changes and
76+
compile as necessary, you can run `Gulp`_ with our development target::
77+
78+
npm run dev
79+
80+
Once you are satisfied with your changes, finalize the bundles (this will
81+
minify library sources)::
82+
83+
npm run build
84+
85+
If you updated any of our vendor libraries, compile those::
86+
87+
npm run vendor
88+
89+
Make sure to check in both files under ``static`` and ``static-src``.
90+
91+
.. note::
92+
93+
We run Gulp through an ``npm`` script in order to ensure
94+
that the correct version from ``package.json`` is used.
95+
96+
Making Changes
97+
--------------
98+
99+
If you are creating a new library, or a new library entry point, make sure to
100+
define the application source file in ``gulpfile.js``, this is not handled
101+
automatically right now.
102+
103+
If you are bringing in a new vendor library, make sure to define the bundles you
104+
are going to create in ``gulpfile.js`` as well.
105+
106+
Tests should be included per-application, in a path called ``tests``, under the
107+
``static-src/js`` path you are working in. Currently, we still need a test
108+
runner that accumulates these files.
109+
110+
Deployment
111+
----------
112+
113+
If merging several branches with JavaScript changes, it's important to do a
114+
final post-merge bundle. Follow the steps above to rebundle the libraries, and
115+
check in any changed libraries.
116+
117+
JavaScript Bundles
118+
------------------
119+
120+
There are several components to our bundling scheme:
121+
122+
Vendor library
123+
We repackage these using `Browserify`_, `Bower`_, and `Debowerify`_ to
124+
make these libraries available by a ``require`` statement. Vendor
125+
libraries are packaged separately from our JavaScript libraries, because
126+
we use the vendor libraries in multiple locations. Libraries bundled
127+
this way with `Browserify`_ are available to our libraries via
128+
``require`` and will back down to finding the object on the global
129+
``window`` scope.
130+
131+
Vendor libraries should only include libraries we are commonly reusing.
132+
This currently includes `jQuery` and `Knockout`. These modules will be
133+
excluded from libraries by special includes in our ``gulpfile.js``.
134+
135+
Minor third party libraries
136+
These libraries are maybe used in one or two locations. They are
137+
installed via `Bower`_ and included in the output library file. Because
138+
we aren't reusing them commonly, they don't require a separate bundle or
139+
separate include. Examples here would include jQuery plugins used on one
140+
off forms, such as jQuery Payments.
141+
142+
Our libraries
143+
These libraries are bundled up excluding vendor libraries ignored by
144+
rules in our ``gulpfile.js``. These files should be organized by
145+
function and can be split up into multiple files per application.
146+
147+
Entry points to libraries must be defined in ``gulpfile.js`` for now. We
148+
don't have a defined directory structure that would make it easy to
149+
imply the entry point to an application library.
150+
151+
.. _`Bower`: http://bower.io
152+
.. _`Gulp`: http://gulpjs.com
153+
.. _`Browserify`: http://browserify.org
154+
.. _`Debowerify`: https://github.com/eugeneware/debowerify
155+
.. _`LESS`: http://lesscss.org
156+
157+
.. _`jQuery`: http://jquery.com
158+
.. _`Knockout`: http://knockoutjs.com

0 commit comments

Comments
 (0)