CONTRIBUTING.md 3.71 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
# Set up

To set up locally, clone this repo and run:

    yarn install
    npm run build     # Optional: build the dist/ directory

Here is a list of npm commands available:

    npm test          # Run all unit tests
    npm run lint      # Check for basic errors using eslint
    npm run server    # Start a HTTP server at the current folder for manual testing
    npm run dev       # Start a rollup watch that re-builds dist/ if files change

S Anand's avatar
S Anand committed
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
# File structure

- `dist/` has output files. It is re-created via  `npm run build`. It has:
  - [g1.js](dist/g1.js) - non-minified source created via rollup on [index.js](index.js)
  - [g1.min.js](dist/g1.min.js) - minified source created via rollup on [index.js](index.js)
  - `<module>.min.js` for each module - minified source created via rollup on `index-<module>.js`
- `./` has setup files.
  - [index.js](index.js) is the rollup configuration to create the full `g1` package
  - `index-<module>.js` is the rollup configuration to create each module
  - Other support files
- `src/` has source files. This includes:
  - `<module>.js` - underlying source for each module, which may import other dependencies. TODO: rename jquery.* to this
  - `<library>.js` - for internally used libraries
- `test/` has test cases. It is run via `npm test`. It has:
  - `test-<module>.html` for each browser module
  - `test-<library>.js` for each library that can be tested directly on node.js
  - `server.js` runs tests on [Puppeteer](https://github.com/GoogleChrome/puppeteer)
  - `tape.js` is dynamically created using browserify to help with test cases. This is not committed
  - Other test dependencies

35
# Interaction conventions
S Anand's avatar
S Anand committed
36

37
All interaction components use this naming convention:
S Anand's avatar
S Anand committed
38

39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
- Interactions are enabled on a *container*, typically `body`. For example,
  `$('body').urlfilter()`. Containers have these common attributes:
    - `data-selector`: selector to identify triggers. e.g. `.urlfilter`, `.highlight`
    - `data-target`: selector that all triggers act on by default
    - `data-mode`: mode of interaction for all triggers
    - `data-attr`: attribute that contains the interaction data, e.g. `href` for `.urlfilter`
    - `data-event`: event that triggers urlfilter. Defaults to `'click'`
- Interactions are triggered on a *trigger*. For example, `.urlfilter` for `$().urlfilter()`.
  Clicking / hovering on / typing in a trigger triggers the interaction.
    - `data-target`: selector that this trigger acts on
    - `data-mode`: mode of interaction for this trigger
- Interactions change a *target*. For example, `urlfilter` changes `location.href` by default. The
  `data-target` on containers and triggers define this.
- Interactions data is contained in an attribute. This is applied to the target. For example,
  `.urlfilter` applied `href` to the target. The attribute name is stored in `data-attr`.
- Interactions have *modes*. This can be controlled using `data-mode=`.
S Anand's avatar
S Anand committed
55

56 57 58
All container `data-` attributes can also be passed as an option to the
function. For example, `<body data-selector=".link">` is the same as
`$('body').urlfilter({selector: '.link'})`.
S Anand's avatar
S Anand committed
59 60

# Release
S Anand's avatar
S Anand committed
61 62 63 64 65

To publish a new version on npm:

    # Run tests on dev branch
    git checkout dev
S Anand's avatar
S Anand committed
66
    npm run lint
S Anand's avatar
S Anand committed
67 68 69
    npm test

    # Update package.json version
S Anand's avatar
S Anand committed
70
    # Update CHANGELOG.md
S Anand's avatar
S Anand committed
71
    # Ensure that there are no build errors on the server
S Anand's avatar
S Anand committed
72
    git commit . -m"DOC: Release version x.x.x"
S Anand's avatar
S Anand committed
73 74 75 76 77 78 79 80 81 82
    git push

    # Merge into dev branch
    git checkout master
    git merge dev
    git tag -a v0.x.x           # Add a one-line summary
    git push --follow-tags
    npm publish               # as sanand0

    git checkout dev
83 84 85 86

Once published:

- Update the version on [gramex/apps/ui/package.json](https://code.gramener.com/cto/gramex/blob/master/gramex/apps/ui/package.json)