Development guidelines - sammich/PegaStudioPro GitHub Wiki

Collection of design/development guidelines I've been following. Some of these came later in development so it might not be applied throughout (yet).

  • New classes should go under PegaStudioPro
  • All new rules not under PegaStudioPro class must be prefixed with PSP_. Includes classless rules (e.g. Controls)
  • The component should not introduce metadata into packaged code
  • The component must not modify any runtime rules (e.g. Process Engine etc.)
  • Consider if a rule should be overridden or copied
    • Where else is it used?
    • Confirm that it doesn't affect the other consumers
    • Would it be simpler to make a 'PSP' copy, and refer to it from our modified calling rule?
    • For example, the branch landing page rules table is populated from an activity and report that's also called from a number of other rules. Our additions could have side effects for those rules, one of which is a slightly increased execution time due to the extra join on the RD. It was refactored to make a 'carbon copy' or PSP copy of the rules and leave the OOTB rules untouched (after withdrawing)
  • Minimise the number of overridden rules to support any particular feature
  • When adding a new configuration
    • Open the config record (class) and update it to reference the Component instead of the PSP dev app
    • Wrap the config usage in a When rule
    • See how other configs are implemented
    • Set a meaningful default
  • Consider if the feature should be an opt-in or opt-out feature
    • Component default enabled (shipped in config)
    • Enabled via PSP user config (see DT which defaults user values)
  • Document the new feature on the Miro board!

Override testing

  • If the rule was originally built before the earliest PSP supported version (e.g. pre-08-06-04) then we only do full testing on the current platform version, currently 8.23.0. Then we just do regression testing for all supported platform versions before release
  • If the rule has multiple OOTB versions

When overriding an OOTB rule

  • Fill out the 'Modding notes' in the side bar
    • Light notes on what was changed, and why
    • These notes will be used when we need to rebuild the rule when an update/patch ships a new version of the rule
  • Fill out the 'copied from version'. Get the value from the modified sibling popup
  • Check all calling rules/references to the overridden rule (also use 'All content' search) to confirm that you will NOT have side effects. We can't be 100% certain, but should have a good understanding of peripheral rules

If making a PSP copy of the rule, the above should also be followed.

Meta

  • All development of the component must be done on the 'PSP Dev' application. It provides rules to support the component's development
  • Rule packaging activities also exist to support a distribution script running externally

Verifying overrides

When an OOTB rule is being overridden, we should check all PSP's supported platform versions to ensure they work correctly there.

  • The lowest version we support is 8.6.0 (technically .3)
  • If we check siblings for the override rule, and the ruleset version of the original rule is 08-06-01 or earlier, it is generally only necessary to fully test on the current platform version, and pre-release regression testing on all supported versions

Creating the override

  • If the rule version is from e.g. 08-08-01 or earlier, we should go into a system of the next earliest version and override that copy, too
    • For example, on Infinity '23 (8.23.0), rule ABC has a version on 08-08-02 (8.8.1), we should log onto a system running 8.8.0 or 8.7.6 to determine what the next earliest version of that rule is
    • If rule ABC, on 8.8.1, indicates that it has copy of the rule originally from 08-07-04 (8.7.3) then we should also go to the latest supported minor version and override it from there
    • Repeat until we get a copy that's sourced from 08-06-01 or the lowest supported patch version (e.g. 08-06-04, 8.6.3)
    • By the end of it we might have these copies of rule ABC for the component:
      • 08-08-02
      • 08-07-04
      • 08-07-01
      • 08-03-01
  • On the rule being overridden, click 'Save as', and put it in a branch suffixed by the RSV of the source (e.g. PSP-08-07-04). Makes it unambiguous about where the rules should be merged to
  • From the target system, export the branch and import it into current version system
    • Using the example above, we would end up with these branches on that PSP Dev app:
      • PSP-08-08-02
      • PSP-08-07-04
      • PSP-08-07-01
      • PSP-08-06-01 (anything earlier than 08-06-01 should just be that)

Supporting new platform versions (minor, patch)

The procedure is the same if it's a minor (8.x) or patch (8.x.y) release.

  • Open the HTML fragment rule SiblingDisplayMain, and at the top, update the array include the ruleset versions we're interested in
    • e.g. 08-08-06 for the 8.8.5 release, or PegaPeerReview_20200528T143606789:01-01-09 etc.
  • Open the PSP rule landing page from the top toolbar
  • For each rule in the 'Overrides' tab, click on the 'Siblings' icon
    • A rule in the indicated RS version will be highlighted, and has therefore been updated in that release
    • If there is a new version, you will need to create a new copy of it (see section 'Creating the override') and manually re-apply all the modifications, based on the modding notes and comments from the earlier modified copy. There may have been non-trivial/non-bug fix changes in the new rule, so be mindful of blindly re-applying the modifications
    • For a PSP or carbon copy rule (e.g. PSP_pzGetRulesInBranch) you will need to search for the OOTB rule by name and do the same

A major version (whenever it happens) will use a new component version, with major skim. But otherwise the above will apply.

Refactoring, Withdrawing

If for any reason, a PSP component rule is not needed either due to refactoring or other reason, withdraw (or block) the rule.

Do not delete a rule that's been released. We must ship the unavailable rules to make them unavailable on the installed system in case a user has skipped a release.

Other remarks

This component's development is relatively sustainable mainly due to the fact that Dev Studio isn't undergoing major development. If you look at the rules in the main ruleset for the component, there aren't many rules outside of the base version (08-06-01).

So on one hand, if the Dev Studio team decides to implement some of PSP's changes, it ironically makes maintaining PSP a little harder. On the other hand, it means more people get a better Dev Studio experience (those who can't/won't install PSP).