Skip to content

Latest commit

 

History

History
116 lines (70 loc) · 4.37 KB

Contributing-Setup.md

File metadata and controls

116 lines (70 loc) · 4.37 KB
Raw

Contributing Setup

Required Software

The requirements to setup, develop, and build this project are listed below.

.NET Runtime

.NET SDK 7.0 or newer

Node.js Runtime

  • Node.js 18.12.0 or newer
  • NVM for Windows to manage multiple installed versions of Node.js
  • See engines in the solution package.json for specific version requirements

C# Editor

  • VS Code
  • Visual Studio
  • Rider

Database

SQL Server 2019 or newer compatible database

SQL Editor

  • MS SQL Server Management Studio
  • Azure Data Studio

Example Project

Database Setup

Running the example project requires creating a new Xperience by Kentico database using the included template.

Change directory in your console to ./examples/DancingGoat and follow the instructions in the Xperience documentation on creating a new database.

Admin Customization

To run the example project Admin customization in development mode, add the following to your User Secrets for the application.

"CMSAdminClientModuleSettings": {
  "kentico-xperience-integrations-lucene-admin": {
    "Mode": "Proxy",
    "Port": 3009
  }
}

The Xperience web application requests client modules from a webpack dev server that runs parallel to the Xperience application.

Changes to client code are immediately integrated and don’t require a restart or rebuild of the web application.

Before you start developing, the webpack server needs to be manually started by running

npm run start

from the root of the module folder, in our case in the /src/Kentico.Xperience.Lucene.Admin/Client folder.

Development Workflow

Prepare your Git branch and commits

  1. Create a new branch with one of the following prefixes

    • feat/ - for new functionality
    • refactor/ - for restructuring of existing features
    • fix/ - for bugfixes

  2. Run dotnet format against the Kentico.Xperience.Lucene solution

    use .NET: format (Lucene) VS Code task.

  3. Commit changes, with a commit message preferably following the Conventional Commits convention.

Test the package locally using the following commands

  1. Generate a local package using the VS Code .NET: pack (Lucene) task or execute its command and arguments at the command line This will generate a new Kentico.Xperience.Lucene.Admin package in the nuget-local folder with a version matching the version in your Directory.Build.props

  2. Update the Directory.Packages.props to populate the Kentico.Xperience.Lucene.Admin package Version="" with the matching the value from the project's Directory.Build.props

    In the future, we will be able to use floating versions to automatically select the highest (local) package version

  3. Build the solution with the LOCAL_NUGET=true property

    You can use the VS Code .NET: build (Solution) - LOCAL_NUGET task

  4. Make sure the Kentico.Xperience.Lucene.Admin.dll version in the examples\DancingGoat\bin\Debug\net6.0\ folder is the right version

  5. Run the DancingGoat application and ensure all functionality is correct

    You can use the .NET Launch (DancingGoat) - LOCAL_NUGET lauch setting in VS Code

  6. Undo the Directory.Packages.props version number change to ensure it is not committed to the repository

  7. Perform a normal build to reset any modified packages.lock.json files

Create a PR

Once ready, create a PR on GitHub. The PR will need to have all comments resolved and all tests passing before it will be merged.

  • The PR should have a helpful description of the scope of changes being contributed.
  • Include screenshots or video to reflect UX or UI updates
  • Indicate if new settings need to be applied when the changes are merged - locally or in other environments