|
| 1 | +# Developing |
| 2 | + |
| 3 | +## Get Started |
| 4 | + |
| 5 | +1. Clone the repository, and `cd` into it. |
| 6 | + |
| 7 | +```sh |
| 8 | +git clone git@github.com:forcedotcom/salesforcedx-templates.git |
| 9 | +``` |
| 10 | + |
| 11 | +2. Ensure you have [Yarn](https://yarnpkg.com/) installed and run the following to build: |
| 12 | + |
| 13 | +``` |
| 14 | +yarn install |
| 15 | +yarn build |
| 16 | +``` |
| 17 | + |
| 18 | +## Branches |
| 19 | + |
| 20 | +- We work in `develop`. |
| 21 | +- Our released (aka. _production_) branch is `main`. |
| 22 | +- Our work happens in _topic_ branches (feature and/or bug-fix). |
| 23 | + - feature as well as bug-fix branches are based on `develop` |
| 24 | + - _Topic_ branches can live in forks (external contributors) or within this repository (committers). |
| 25 | + \*\* When creating _topic_ branches in this repository please prefix with `<developer-name>/`. |
| 26 | + - branches _should_ be kept up-to-date using `rebase` |
| 27 | + - see below for further merge instructions |
| 28 | + |
| 29 | +### Merging between branches |
| 30 | + |
| 31 | +- We try to limit merge commits as much as possible. |
| 32 | + |
| 33 | + - They are usually only ok when done by our release automation. |
| 34 | + |
| 35 | +- _Topic_ branches are: |
| 36 | + |
| 37 | + 1. based on `develop` and will be |
| 38 | + 1. squash-merged into `develop`. |
| 39 | + |
| 40 | +- Hot-fix branches are an exception. |
| 41 | + - Instead we aim for faster cycles and a generally stable `develop` branch. |
| 42 | + |
| 43 | +### Merging `develop` into `main` |
| 44 | + |
| 45 | +- When a development cycle finishes, the content of the `develop` branch will become the `main` branch |
| 46 | + |
| 47 | +``` |
| 48 | +$ git checkout main |
| 49 | +$ git reset --hard develop |
| 50 | +$ |
| 51 | +$ # Using a custom commit message for the merge below |
| 52 | +$ git merge -m 'Merge -s our (where _ours_ is develop) releasing stream x.y.z.' -s ours origin/main |
| 53 | +$ git push origin main |
| 54 | +``` |
| 55 | + |
| 56 | +### Making Pull Requests |
| 57 | + |
| 58 | +Take a look at [CONTRIBUTING](../CONTRIBUTING.md) doc for making and merging pull requests. |
| 59 | + |
| 60 | +## Developing Plugin |
| 61 | + |
| 62 | +To test plugin locally, use `bin/run` in place of `sfdx`. For example: |
| 63 | + |
| 64 | +```sh |
| 65 | +./bin/run force:apex:class:create --classname 'TestClass' --template 'DefaultApexClass' --outputdir ./testsoutput/myApex/ |
| 66 | +``` |
| 67 | + |
| 68 | +To test plugin locally with Salesforce CLI, add `"@salesforce/templates": "file://path/to/packages/templates"` to the plugin's `package.json`. |
| 69 | + |
| 70 | +Link your plugin to Salesforce CLI: |
| 71 | + |
| 72 | +```sh |
| 73 | +sfdx plugins:link . |
| 74 | +``` |
| 75 | + |
| 76 | +Verify plugin is linked: |
| 77 | + |
| 78 | +```sh |
| 79 | +sfdx plugins |
| 80 | +``` |
| 81 | + |
| 82 | +### Debugging Your Plugin |
| 83 | + |
| 84 | +We recommend using the Visual Studio Code (VS Code) IDE for your plugin development. Included in the `.vscode` directory of this plugin is a `launch.json` config file, which allows you to attach a debugger to the node process when running your commands. |
| 85 | + |
| 86 | +To debug the `hello:org` command: |
| 87 | + |
| 88 | +1. If you linked your plugin to the Salesforce CLI, call your command with the `dev-suspend` switch: |
| 89 | + |
| 90 | +```sh-session |
| 91 | +$ sfdx hello:org -u myOrg@example.com --dev-suspend |
| 92 | +``` |
| 93 | + |
| 94 | +Alternatively, to call your command using the `bin/run` script, set the `NODE_OPTIONS` environment variable to `--inspect-brk` when starting the debugger: |
| 95 | + |
| 96 | +```sh-session |
| 97 | +$ NODE_OPTIONS=--inspect-brk bin/run hello:org -u myOrg@example.com |
| 98 | +``` |
| 99 | + |
| 100 | +2. Set some breakpoints in your command code. |
| 101 | +3. Click on the Debug icon in the Activity Bar on the side of VS Code to open up the Debug view. |
| 102 | +4. In the upper left hand corner of VS Code, verify that the "Attach to Remote" launch configuration is selected. |
| 103 | +5. Hit the green play button to the left of the "Attach to Remote" launch configuration window. The debugger should now be suspended on the first line of the program. |
| 104 | +6. Hit the green play button at the top middle of VS Code (this play button is to the right of the play button that you clicked in step #5). |
| 105 | + <br><img src="../.images/vscodeScreenshot.png" width="480" height="278"><br> |
| 106 | + Congrats, you are debugging! |
| 107 | + |
| 108 | +## Developing Library |
| 109 | + |
| 110 | +Adding a new template: |
| 111 | + |
| 112 | +1. Define a new template type in `TemplateType`, and add available template options extending `TemplateOptions` in library [types](../packages/templates/src/utils/types.ts). |
| 113 | +2. Create a generator extending [`SfdxGenerator`](../packages/templates/src/generators/sfdxGenerator.ts) in [generators](../packages/templates/src/generators) folder. Take a look at [`ApexClassGenerator`](../packages/templates/src/generators/apexClassGenerator.ts) for an example. |
| 114 | + |
| 115 | +- Generator class file should default export a generator class extending `SfdxGenerator` |
| 116 | +- Generator class file should have a name same as the template type's name, except with the first letter lowercased |
| 117 | + |
| 118 | +## Testing |
| 119 | + |
| 120 | +Run the following to test library and plugin: |
| 121 | + |
| 122 | +```sh |
| 123 | +yarn test |
| 124 | +``` |
| 125 | + |
| 126 | +If you are using VS Code for development, the following launch configurations are available: "Run All Tests", "Run Current Test", "Run Current Test Without Compile". Have `"debug.javascript.usePreview": true` in your user setting enabled so you can utilize [`vscode-js-debug`](https://github.com/microsoft/vscode-js-debug) debugger. This setting is enabled by default in VS Code version 1.47. |
0 commit comments