CONTRIBUTING.md 4.24 KB
Newer Older
1 2 3 4 5 6 7 8 9
# 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:

10
    npm test          # Run all unit tests on puppeteer
11 12 13 14
    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

15 16 17 18 19 20
To test unit tests on other browsers using Selenium:

- `npm run test-chrome`. Requires [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/downloads) in your PATH
- `npm run test-edge`. Requires [WebDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/) in your PATH
- `npm run test-firefox`. Requires [GeckoDriver](https://github.com/mozilla/geckodriver/releases/) in your PATH

S Anand's avatar
S Anand committed
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
# 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)
S Anand's avatar
S Anand committed
38
  - `tape.js` is dynamically created using browserify to help with test cases. This is not committed. To locally create `tape.js` file, run `npm test`.
S Anand's avatar
S Anand committed
39 40
  - Other test dependencies

41
# Interaction conventions
S Anand's avatar
S Anand committed
42

43
All interaction components use this naming convention:
S Anand's avatar
S Anand committed
44

45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
- 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
61

62 63 64
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
65 66

# Release
S Anand's avatar
S Anand committed
67 68 69 70 71

To publish a new version on npm:

    # Run tests on dev branch
    git checkout dev
S Anand's avatar
S Anand committed
72
    npm run lint
S Anand's avatar
S Anand committed
73
    npm test
74 75 76
    npm test-chrome
    npm test-edge
    npm test-firefox
S Anand's avatar
S Anand committed
77 78

    # Update package.json version
S Anand's avatar
S Anand committed
79
    # Update CHANGELOG.md
S Anand's avatar
S Anand committed
80
    # Ensure that there are no build errors on the server
S Anand's avatar
S Anand committed
81
    git commit . -m"DOC: Release version x.x.x"
S Anand's avatar
S Anand committed
82 83 84 85 86 87 88 89 90 91
    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
92 93 94 95

Once published:

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