|
| 1 | +Guide for Hub team on how to work with Hub.js |
| 2 | + |
| 3 | +# Why are we moving logic into Hub.js? |
| 4 | + |
| 5 | +We want to extract business logic from the Ember app, and move it into a strongly typed, highly-tested set of packages so we are able to... |
| 6 | + |
| 7 | +- streamline the logic in the app itself |
| 8 | + - single hub.js call, vs orchestrating a dozen rest-js calls |
| 9 | +- provide a set of libraries for "automating" hub |
| 10 | +- leverage the same logic in Hub Stencil components that can be used outside of the application |
| 11 | +- encapsulate the same logic in a REST API (long-term) |
| 12 | + |
| 13 | +# How do I move logic into Hub.js? |
| 14 | + |
| 15 | +There are a number of common workflows when working with Hub.js and the Hub Ember application |
| 16 | + |
| 17 | +## Adding Functions to Hub.js for use in Stencil Components |
| 18 | + |
| 19 | +This should be the dominant workflow from July 2021 forward. |
| 20 | + |
| 21 | +- develop Stencil component in `hub-components`, testing things in Storybook |
| 22 | +- use existing Hub.js functions, until you need something that's not present yet |
| 23 | +- add util to the `hub-components` repo, where you write function in typescript |
| 24 | +- use Storybook to verify the function and the component work as you want them to |
| 25 | +- add the function to the appropritate package in Hub.js and add tests |
| 26 | +- open Hub.hs PR, get it approved & merged |
| 27 | +- cut a release (see Releasing section below) |
| 28 | +- bump hub.js version in `hub-components` and install |
| 29 | +- re-verify component operates as expected |
| 30 | +- PR to `hub-components`, merge, release, consume component in Hub Ember app |
| 31 | + |
| 32 | +## Adding a Function in Hub.js that is used in a Ember route/controller/component |
| 33 | + |
| 34 | +This is the pre-July 2021 workflow [More details here](https://github.com/ArcGIS/opendata-ui/blob/master/docs/migrate-to-hub-js.md) |
| 35 | + |
| 36 | +- work in Ember app, creating component/route/controller etc |
| 37 | +- use existing Hub.js functions, until you need something that's not present yet |
| 38 | +- add a util to the Ember app, write the needed function(s) in there |
| 39 | +- get it working the way you need it to |
| 40 | +- PR feature into Hub app repo |
| 41 | +- add the function to the appropritate package in Hub.js and add tests |
| 42 | +- open Hub.hs PR, get it approved & merged |
| 43 | +- cut a release (see Releasing section below) |
| 44 | +- bump hub.js version in Hub App and install |
| 45 | +- remove utility function(s) |
| 46 | +- import functions from Hub.js package |
| 47 | +- re-verify component/route/controller operates as expected |
| 48 | +- PR to Hub App, removing the util, adding the Hub.js version bump |
| 49 | + |
| 50 | +## Small changes to a Function in Hub.js |
| 51 | + |
| 52 | +The easiest thing to do is edit the function in the hub.js package, under `node_modules`. You can then verify it within the ember app, and when its working... |
| 53 | + |
| 54 | +- add/update the function to the appropritate package in Hub.js and add tests |
| 55 | +- open Hub.hs PR, get it approved & merged |
| 56 | +- cut a release (see Releasing section below) |
| 57 | +- bump hub.js version in Hub App and `yarn` to install |
| 58 | +- verify things work |
| 59 | +- PR to Hub App to bump Hub.js package version |
| 60 | + |
| 61 | +> **Reminder**: when you make changes to files under `node_modules` you need to re-start ember. |
| 62 | +> **Reminder**: you will lose all changes made in `node_modules` when you `yarn` |
| 63 | +
|
| 64 | +## Large changes to a Function in Hub.js |
| 65 | + |
| 66 | +This is where things get complex. We have a few options: |
| 67 | + |
| 68 | +- work within the Hub.js repo, leverage "e2e" subsystem to verify actual network calls etc |
| 69 | +- `npm link` between Hub.js and the Hub Ember app |
| 70 | + |
| 71 | +### Hub.js e2e Tests |
| 72 | + |
| 73 | +Hub.js has e2e test infrastructure, but it is _not_ intended to be run on a regular basis or drive code-coverage. Instead, it's a means to verify the underlying API calls, in a browser, without having to "link" into a UI app (Stencil or Hub app). |
| 74 | + |
| 75 | +# Sematic Commit Messages |
| 76 | + |
| 77 | +As of June 24th, 2021, pull requests to Hub.js will require at least one [conventional commit message](https://www.conventionalcommits.org/en/v1.0.0/#summary) in order to automatically generate the CHANGELOG.md entries during the release process. |
| 78 | + |
| 79 | +The easiest way to do this is by running `npm run c` instead of `git commit...`. Alternatively you can structure your commit message so it aligns with the standard. |
| 80 | + |
| 81 | +Pattern: `<type>(package): message` |
| 82 | + |
| 83 | +Types: `feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert` |
| 84 | +Package: `hub-sites, hub-common etc`. This is optional if the commit touches multiple packages. |
| 85 | + |
| 86 | +# Breaking Changes |
| 87 | + |
| 88 | +This project follows [semantic versioning](https://semver.org/), and in general, we want to avoid breaking changes, as that requires all consuming projects to bump their versions vs automatically getting updates by using semver ranges. |
| 89 | + |
| 90 | +If we must make a change that is breaking (typically changing fn arguments or return values), we try to stage it out as follows: |
| 91 | + |
| 92 | +- create a new fn, with the new params, add tests etc |
| 93 | +- add deprecation warning to old fn similar to what's shown below |
| 94 | + |
| 95 | +```` |
| 96 | +// TODO: remove this at next breaking version |
| 97 | +/** |
| 98 | + * ```js |
| 99 | + * import { getCategory } from "@esri/hub-common"; |
| 100 | + * // |
| 101 | + * getCategory('Feature Layer') |
| 102 | + * > 'dataset' |
| 103 | + * ``` |
| 104 | + * **DEPRECATED: Use newFunction() instead** |
| 105 | + * returns the Hub category for a given item type |
| 106 | + * @param itemType The ArcGIS item type |
| 107 | + * @returns the category of a given item type. |
| 108 | + */ |
| 109 | +export function oldFunction(itemType: string = ""): string { |
| 110 | + /* tslint:disable no-console */ |
| 111 | + console.warn( |
| 112 | + "DEPRECATED: Use newFunction() instead. oldFunction will be removed at vX.0.0" |
| 113 | + ); |
| 114 | +```` |
| 115 | + |
| 116 | +- PR the change, and denote it as a `feat` which will indicate a "minor" release |
| 117 | + |
| 118 | +This allows consumers to get the updated function, see the deprecation warning in their console, and then make changes in their app. |
| 119 | + |
| 120 | +When we plan a major release, as part of that process we go through the codebase, searching for the `// TODO: remove this at next breaking version` comments, and removing them. |
| 121 | + |
| 122 | +Those commits should have messages with a `!` in them to denote a breaking change |
| 123 | + |
| 124 | +``` |
| 125 | +$ git commit -m 'refactor!: remove oldFunction' |
| 126 | +``` |
| 127 | + |
| 128 | +That will indicate a major release is needed for that commit. |
| 129 | + |
| 130 | +## Releasing |
| 131 | + |
| 132 | +Currently the release process is semi-automated. And it's picky... so for now, after you get your PR approved and merge it, ask Tom or Dave to cut a release. |
| 133 | + |
| 134 | +Longer term we want to move to automating the release process via [semantic release](https://semantic-release.gitbook.io/semantic-release/) which is a set of patterns that enables CI to automate the release process. |
0 commit comments