CONTRIBUTING.md 4.3 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
S Anand's avatar
S Anand committed
74
75
76
    npm run test-chrome
    npm run test-edge
    npm run 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
    git push

    # Merge into dev branch
    git checkout master
    git merge dev
87
    git tag -a v0.x.x -m"Add a one-line summary"
S Anand's avatar
S Anand committed
88
    git push --follow-tags
89
90
91
92

    # Publish to https://www.npmjs/package/g1
    # Maintained currently by @sanand0
    npm publish
S Anand's avatar
S Anand committed
93
94

    git checkout dev
95
96
97
98

Once published:

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