diff --git a/.github/workflows/essentialsplugins-updatereadme-caller.yml b/.github/workflows/essentialsplugins-updatereadme-caller.yml index e3680bd..8f4bbe3 100644 --- a/.github/workflows/essentialsplugins-updatereadme-caller.yml +++ b/.github/workflows/essentialsplugins-updatereadme-caller.yml @@ -8,7 +8,7 @@ on: jobs: call-update-readme: - uses: PepperDash/workflow-templates/.github/workflows/update-readme.yml@development + uses: PepperDash/workflow-templates/.github/workflows/update-readme.yml@main with: target-branch: ${{ github.ref_name }} diff --git a/Readme-Upgrade-to-4Series.md b/Readme-Upgrade-to-4Series.md new file mode 100644 index 0000000..d41cc6b --- /dev/null +++ b/Readme-Upgrade-to-4Series.md @@ -0,0 +1,110 @@ +![PepperDash Essentials Plugin Logo](/images/essentials-plugin-blue.png) + +# Upgrading an EPI: Essentials v1.x → v2.x + +## Preparation + +1. **Clone the Template Repo referred to as TR** to your local machine. + - [EssentialsPluginTemplate](https://github.com/PepperDash/EssentialsPluginTemplate) +2. **Checkout `main` branch** in the TR. + +## Branching + +4. In your EPI repo: + - Confirm it does **not already support Essentials v2.x**. + - Ensure there is **no existing 4-series update branch**. + - Create a new branch (e.g., `feature/4-series-updates`) from `main`. + +## Upgrade Steps + +5. In the new branch: + - **Replace** EPI `.github` files/folders with those from TR as needed. + - *Note:* Retain any custom workflows if required. Consult with PepperDash Team if unsure. + - **Copy** the following from TR to EPI: + - `.releaserc.json` (root) + - `epi-make-model.4Series.sln` (root) + - `src/epi-make-model.4Series.csproj` (create `src` folder if missing) + - `images` folder (if your `readme.md` lacks the standard logo) + - **Initial Commit:** Commit changes, but do **not** push yet. + +6. **If EPI has a `src/*.nuspec` file:** + - Record these values from `Nuspec` for later: + - `` (Package ID) + - `` (Project URL) + - `` (Assembly Title) + +7. **Open Solution:** + - Open `epi-make-model.4Series.sln` in Visual Studio 2022. + - If errors occur, ensure the `.csproj` file is located within `src` folder. + +8. **Update Project Properties:** + - In `src/epi-make-model.4Series.csproj`, update: + - `AssemblyTitle` (from nuspec `<title>`) + - `RootNamespace` (from existing EPI, device namespace actual) + - `PackageProjectUrl` (from nuspec `<projectUrl>`) + - **Rename `make-model` build path references shown below:** + + ![defineBuildObjectstoRemove](/images/upgrade-to-4Series/removeObsoleteReferences.png) + - **Add runtime exclusion:** + Add `<ExcludeAssets>runtime</ExcludeAssets>` to the PepperDash Essentials `PackageReference`. + + ![addRuntimeExclusion](/images/upgrade-to-4Series/addRuntumeExclusion.png) + +9. **Copy Build Files:** + - Copy `src/Directory.Build.props` and `src/Directory.Build.targets` from TR. + - Update `RepositoryUrl` in `Directory.Build.props` to match nuspec `PackageProjectUrl`. + - Remove "template" text from `<Product>` in `Directory.Build.props` as needed. + +10. **Clean Up:** + - Delete old Visual Studio 2008 files: `.sln`, `.suo`, `.nuspec`, `.csproj`, `.csproj.user`, `.projectinfo`. + - Ensure file structure matches below example: +``` + ├── src/ + │ ├── Directory.Build.props + │ ├── Directory.Build.tagets + │ ├── *.3Series.csproj + │ └── *.4Series.csproj + ├── .releaserc.json + ├── *.3Series.sln + ├── *.4Series.sln + ├── LICENSE.md + └── README.md +``` + +11. **Rename Solution/Project** as needed. + + ![renameEpiSolution](/images/upgrade-to-4Series/renameEpiSolution.png) + +12. **Update Project References and Dependencies** + - Remove old PepperDash Essentials dependency. + - Add PepperDash Essentials v2.x dependency via Visual Studio 2022 > Project > `Manage Nuget Packages`. + + ![removeExistingReferences](/images/upgrade-to-4Series/removeExistingDependencies.png) + +13. **Update Factory Class:** + Set `MinimumEssentialsFrameworkVersion` to match the Essentials version dependency. + +14. **Build Solution:** + Ensure solution compiles (warnings about obsolete `Debug.Console` calls are OK). + +15. **Update Debug Calls:** + Replace `Debug.Console` with `Debug.Log` methods as appropriate (see table). + + ![replaceDebugConsoleMethods](/images/upgrade-to-4Series/replaceExistingDebugConsoleMethods.png) + +## Completion Checklist + +- [ ] EPI compiles with **no warnings**. +- [ ] **Obsolete methods** updated to modern equivalents. +- [ ] **Workflows** complete successfully; packages generated via GitHub and NuGet.org. +- [ ] `readme.md` includes: + - Usage/setup instructions + - Example SIMPL Windows bridge joinmap + - Example device communication structure/properties +- [ ] EPI tested against full release Essentials version. +- [ ] EPI tested by another developer. +- [ ] Full release of EPI. + +--- + +*For questions about workflows or customizations, consult with PepperDash Team.* \ No newline at end of file diff --git a/images/upgrade-to-4Series/addRuntumeExclusion.png b/images/upgrade-to-4Series/addRuntumeExclusion.png new file mode 100644 index 0000000..5ab0b9a Binary files /dev/null and b/images/upgrade-to-4Series/addRuntumeExclusion.png differ diff --git a/images/upgrade-to-4Series/removeExistingDependencies.png b/images/upgrade-to-4Series/removeExistingDependencies.png new file mode 100644 index 0000000..7c7fef2 Binary files /dev/null and b/images/upgrade-to-4Series/removeExistingDependencies.png differ diff --git a/images/upgrade-to-4Series/removeObsoleteReferences.png b/images/upgrade-to-4Series/removeObsoleteReferences.png new file mode 100644 index 0000000..9392793 Binary files /dev/null and b/images/upgrade-to-4Series/removeObsoleteReferences.png differ diff --git a/images/upgrade-to-4Series/renameEpiSolution.png b/images/upgrade-to-4Series/renameEpiSolution.png new file mode 100644 index 0000000..1cf19a1 Binary files /dev/null and b/images/upgrade-to-4Series/renameEpiSolution.png differ diff --git a/images/upgrade-to-4Series/replaceExistingDebugConsoleMethods.png b/images/upgrade-to-4Series/replaceExistingDebugConsoleMethods.png new file mode 100644 index 0000000..2b79542 Binary files /dev/null and b/images/upgrade-to-4Series/replaceExistingDebugConsoleMethods.png differ diff --git a/src/Directory.Build.props b/src/Directory.Build.props index db59da5..206b6c0 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -2,14 +2,14 @@ <PropertyGroup> <Version>1.0.0-local</Version> <InformationalVersion>$(Version)</InformationalVersion> - <Authors>PepperDash Technologies</Authors> - <Company>PepperDash Technologies</Company> + <Authors>PepperDash Technology</Authors> + <Company>PepperDash Technology</Company> <Product>PepperDash Essentials Plugin Template</Product> <Copyright>Copyright © 2025</Copyright> <RepositoryUrl>https://github.com/PepperDash/EssentialsPluginTemplate.git</RepositoryUrl> <RepositoryType>git</RepositoryType> <PackageTags>Crestron; 4series</PackageTags> - <PackageOutputPath>../output</PackageOutputPath> + <PackageOutputPath>..\output</PackageOutputPath> <GeneratePackageOnBuild>True</GeneratePackageOnBuild> <PackageLicenseFile>LICENSE.md</PackageLicenseFile> <PackageReadmeFile>README.md</PackageReadmeFile> diff --git a/src/epi-make-model.4Series.csproj b/src/epi-make-model.4Series.csproj index 59740a8..7ac4bfa 100644 --- a/src/epi-make-model.4Series.csproj +++ b/src/epi-make-model.4Series.csproj @@ -7,14 +7,14 @@ <RootNamespace>PepperDash.Essentials.Plugin</RootNamespace> <Deterministic>false</Deterministic> <AssemblyTitle>PepperDash.Essentials.Plugin.Make.Model</AssemblyTitle> - <Company>PepperDash Technologies</Company> + <Company>PepperDash Technology</Company> <Description>This software is a template for a PepperDash Essentials Plugin.</Description> <Copyright>Copyright 2025</Copyright> <Version>1.0.0-local</Version> <GenerateAssemblyInfo>true</GenerateAssemblyInfo> <InformationalVersion>$(Version)</InformationalVersion> - <OutputPath>4Series\bin\$(Configuration)\</OutputPath> - <Authors>PepperDash Technologies</Authors> + <OutputPath>bin\$(Configuration)\</OutputPath> + <Authors>PepperDash Technology</Authors> <PackageId>Pepperdash.Essentials.Plugins.Template</PackageId> <PackageProjectUrl>https://github.com/PepperDash/EssentialsPluginTemplate.git</PackageProjectUrl> <PackageTags>crestron 4series essentials plugin template</PackageTags> @@ -35,7 +35,9 @@ </ItemGroup> <ItemGroup> - <PackageReference Include="PepperDashEssentials" Version="2.0.0-hotfix-2613" /> + <PackageReference Include="PepperDashEssentials" Version="2.0.0" > + <ExcludeAssets>runtime</ExcludeAssets> + </PackageReference> </ItemGroup> <ItemGroup> @@ -45,4 +47,4 @@ <ItemGroup> <None Remove="../output\epi-make-model.4Series.1.0.0-local.cplz" /> </ItemGroup> -</Project> \ No newline at end of file +</Project>