docs: add major version upgrade documentation (#647)

* docs: add major version upgrade documentation * docs: general updating of stale docs * docs: clean up md linting errors
uPortal-Attic · Dec 20, 2017 · 7aeeba3 · 7aeeba3
1 parent 9ad530b
commit 7aeeba3
Show file tree

Hide file tree

Showing 13 changed files with 75 additions and 94 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -43,8 +43,10 @@ With gratitude to the many [contributors to this project](contributors.md).
 
 ## Administration
 
++ [Major version upgrade guide](upgrading.md)
 + [Release management](releasing.md)
-+ [Frame versions with docs and release notes](versions.md)
++ [Frame versions with docs and release notes][CHANGELOG]
 
 [uportal-home]: https://github.com/uPortal-Project/uportal-home
 [MyUW]: https://it.wisc.edu/services/myuw/
+[CHANGELOG]: https://github.com/uPortal-Project/uportal-app-framework/blob/master/CHANGELOG.md
diff --git a/docs/announcements.md b/docs/announcements.md
diff --git a/docs/app-options.md b/docs/app-options.md
@@ -1,6 +1,6 @@
 # App options
 
-Apps using the `<app-header>` or `<frame-page>` [directives](directives.md) can specify custom app-specific options to appear in the app header, as pictured below.
+Apps using the `<frame-page>` [directive](directives.md) can specify custom app-specific options to appear in the app header, as pictured below.
 
 ![./img/app-header-options.png](img/app-header-options.png)
 

diff --git a/docs/buttons.md b/docs/buttons.md
@@ -2,7 +2,7 @@ Buttons in uportal-app-framework leverage [Angular Material buttons](https://mat
 Google Material design practices and come with built-in UX enhancements. Use the `<md-button>` directive to create a material button.
 
 #### All buttons should have the following attributes:
-+ The text should be sentence-case (e.g. "Reset announcements")
++ The text should be sentence-case (e.g. "Learn more")
 + It should include an `aria-label` attribute that describes the action for screen readers
 + It should have either an `ng-click` or `ng-href` attribute for buttons and links, respectively
 + It should include a class for the desired color palette (i.e. `md-primary`, `md-accent`, `md-warn`, or `md-default`)

diff --git a/docs/directives.md b/docs/directives.md
@@ -5,8 +5,6 @@
 Frame page should be used for all pages in a uportal-app-framework application. It comes with much of the rest of the framework's skeleton built in, including the app-header and main-menu directives. You should use it as the outermost element for
 each of your application's main views.
 
-**Example page**: see `/portal/main/partials/example-page.html`
-
 ### Template:
 
 ```html
@@ -24,38 +22,12 @@ each of your application's main views.
 
 ### Params
 
-_See `app-header`_
-
-### Options
-
+* **app-title**: The title that will be displayed in the app header
+* **app-icon**: The icon to use as a prefix to the app title. You can use Font Awesome (i.e. "fa-envelope") or Material Icons (i.e. "email").
+* **app-show-add-to-home**: If set to true, will include the add-to-home directive and its controller in the app header (used for apps that are part of the portal ecosystem).
+* **app-fname**: If provided, it will be used in the add-to-home feature. If not, it'll try to use NAMES.fname constant.
 * **white-background**: A boolean when set to true with give you a white background.
 
-## App header
-
-If you don't want to use the frame page directive, you can still utilize the app-header as you would any other directive. It should be included in all pages of your app.
-
-There is also a directive called `app-header-two-way-bind`. This has all the same features as `app-header` except all the scope attributes are passed in via `=` instead of `@`. This provides 2 way binding for your header. Research angular directives for more details.
-
-### Template:
-
-```html
-<app-header
-  app-title="Hello World"
-  app-icon="email"
-  app-fname="hey-world-fname"
-  app-show-add-to-home="false"
-></app-header>
-```
-
-### Params:
-
-All params are prefixed with `app-`.
-
-* **title**: The title that will be displayed in the app header
-* **icon**: The icon to use as a prefix to the app title. You can use Font Awesome (i.e. "fa-envelope") or Material Icons (i.e. "email").
-* **show-add-to-home**: If set to true, will include the add-to-home directive and its controller in the app header (used for apps that are part of the portal ecosystem).
-* **fname**: If provided, it will be used in the add-to-home feature. If not, it'll try to use NAMES.fname constant.
-
 ## Main menu
 
 Makes the side navigation menu available. If you have [configured](configuration.md) either the `appMenuTemplateURL` or `appMenuItems` option, you need to include this directive on every page where you want navigation. For this reason, using the frame-page directive for all your pages is recommended.

diff --git a/docs/latest/README.md b/docs/latest/README.md
diff --git a/docs/latest/index.html b/docs/latest/index.html
diff --git a/docs/material.md b/docs/material.md
@@ -14,7 +14,7 @@ This page will serve as a resource for Material documentation, and how MyUW uses
 + **[Cards](https://material.angularjs.org/latest/demo/card)**: Used for MyUW widgets, Note there are many parts to a card, including title, media, actions, and content. Use the Angular Material documentation to guide you.
 + **[Toolbar](https://material.angularjs.org/latest/demo/toolbar)**: Used for the MyUW header.
 + **[Menu](https://material.angularjs.org/latest/demo/menu)**: Used for MyUW's username, options, and mobile menus.
-+ **[Dialog](https://material.angularjs.org/latest/demo/dialog)**: Used for feature announcements and app ratings in MyUW.
++ **[Dialog](https://material.angularjs.org/latest/demo/dialog)**: Used sparingly for feature announcements in MyUW.
 + **[Input](https://material.angularjs.org/latest/demo/input)**: Bootstrap input components are being phased out in favor of Material input directives throughout MyUW.
 + **[Loading icon](https://material.angularjs.org/latest/demo/progressCircular)**: Use the Material Progress Circular directive for loading screens in MyUW. This can be colored according to the school's material theme.
 + **[Radio Buttons](https://material.angularjs.org/latest/demo/radioButton)**, **[Selects](https://material.angularjs.org/latest/demo/select)**, **[Checkboxes](https://material.angularjs.org/latest/demo/checkbox)**, and **[Switches](https://material.angularjs.org/latest/demo/switch)**: Material's input components are fantastic and should be used throughout MyUW.

diff --git a/docs/notifications.md b/docs/notifications.md
diff --git a/docs/overview.md b/docs/overview.md
@@ -23,7 +23,7 @@ In addition to the features pictured above, frame provides:
 + Error pages
 + Optional settings
 + [Frame-specific angular directives](directives.md)
-+ [Mascot announcements and notifications](announcements.md)
++ [Mascot announcements and notifications](messaging.md)
 + Optimizations for small screens (including the [mobile menu](img/mobile-menu.png))
 
 In-depth overviews of frame's features can be found under the Features heading on the [documentation home page](README.md).
diff --git a/docs/theming.md b/docs/theming.md
@@ -53,7 +53,7 @@ var example = {
 + `ariaLabelTitle`: The aria label put in place of the theme title
 + `crestalt`: The crest alt text. This should be the name of your frame app (i.e. "MyUW Portal").
 + `group`: Groups this app should be enabled for automatically. Not sure? Ask the dev list: <https://groups.google.com/a/apereo.org/forum/#!forum/uportal-dev>.
-+ `mascotImg` (optional): See documentation about the mascot for announcements [here](announcements.md).
++ `mascotImg` (optional): See documentation about the mascot for announcements [here](messaging.md).
 + `profileUrl` (optional): Specify a URL for a "Profile" app/page, where users can view and/or update their personal information.
 + `footerLinks`: An array of links which appear in the footer -- typically contains links to the campus help desk and feedback portal.
 + `materialTheme`: \[object or string] See the *Material Theme* section below.

diff --git a/docs/upgrading.md b/docs/upgrading.md
@@ -0,0 +1,63 @@
+# Upgrading
+At a glance notes for upgrading apps between major versions.
+
+# 6.x.x to 7.x.x
+- Wrap routed views in a `<frame-page>` directive.
+  - remove extraneous `<app-header>` directives.
+- Remove `app-options-template` attribute from existing `<frame-page>` directives. Replace with a partial in `overrides.js`:
+  - from
+    ```html
+    <frame-page app-title="App Name Here"
+          app-icon="fa-clock-o"
+          white-background='false'
+          app-option-template="{{vm.showAdminPanel ? 'my-app/admin-actions/adminActionsSidebarToggle.html' : ''}}"
+          app-single-option="true">
+    ```
+  - to
+    ```html
+    <frame-page app-title="App Name Here"
+          app-icon="fa-clock-o"
+          white-background='false'>
+    ```
+    ```javascript
+    var example = {
+      'APP_OPTIONS': {
+        'optionsTemplateURL': 'my-app/app-options/appOptions.html',
+      },
+    };
+    ```
+
+# 5.x.x to 6.x.x
+- Change pom.xml to reflect new dependency version (and name).
+  - from
+    ```xml
+    <dependency>
+      <groupId>edu.wisc.my.apps</groupId>
+      <artifactId>uw-frame</artifactId>
+      <type>war</type>
+      <version>5.2.1</version>
+    </dependency>
+    ```
+  - to
+    ```xml
+    <dependency>
+      <groupId>org.apereo.uportal</groupId>
+      <artifactId>uportal-app-framework</artifactId>
+      <type>war</type>
+      <version>6.0.0</version>
+    </dependency>
+    ```
+
+# 4.x.x to 5.x.x
+- Update the notifications page url attribute name in `override.js` (note the pluralization)
+  - from `NOTIFICATIONS.notificationFullURL`
+  - to `MESSAGES.notificationsPageURL`
+- Update location for getting notifications feed in `override.js`
+  - from `SERVICE_LOC.notificationsURL`
+  - to `SERVICE_LOC.messagesURL`
+- Remove `NOTIFICATIONS` and `FEATURES` attribute groups from `override.js`
+- Add a default theme configuration to override.js
+  - e.g. set `APP_FLAGS.defaultTheme` to `'uw-madison'`
+
+# 3.x.x to 4.x.x
+- Rename custom directives that include the word `widget`
diff --git a/docs/versions.md b/docs/versions.md