Table of Contents

QuickStart guide

Creating and Maintaining a custom Swift project for DynamicWeb 10

This guide outlines the process for creating a custom website based on the public Swift GitHub repository.

It includes instructions for cloning the Swift repository, customizing it, and maintaining your custom project by incorporating updates from the original Swift repository.

To customize Swift, you’ll typically use regular frontend development tools like VS Code (available on Windows and Mac), Visual Studio (for Windows), or another popular code editor for Mac.

Before starting, ensure you have the required tools installed:

  • Git: For cloning and managing repositories
  • A code editor such as VS Code, Visual Studio, or another editor of your choice

1. Clone the Swift repository

To get started, clone the Swift repository to your local machine:

  1. Open a terminal in VS Code or your preferred Git-enabled terminal

  2. Run the following command:

    git clone https://github.com/dynamicweb/Swift.git

  3. Navigate to the cloned repository:

    cd Swift

You now have a local copy of the Swift repository.

2. Create a custom repository

To store and manage your customized project, create a new Git repository:

  1. Navigate to Azure DevOps

  2. Create a new Git repository

  3. Add the Azure DevOps repository as a remote:

    git remote add origin <Your_Azure_DevOps_Repo_URL>

  4. Push your changes to the repository:

    git push -u origin main

Your custom project is now stored in your own repository.

3. Customizing the Swift project

To customize the Swift project:

  1. Modify Files: Edit the existing templates, CSS, and JavaScript files in the repository to fit your project requirements

  2. Add New Files: Add any new files required for your project (e.g., custom styles or templates)

  3. Create a Feature Branch and Make Changes:

    • To work on new features or customizations, create a feature branch:

      git checkout -b feature/<feature-name>

    • Make your changes in the branch.

    • Test your updates as described below.

    • Once satisfied, push the branch to your repository:

      git push origin feature/<feature-name>

    • Open a pull request from your feature branch to the main branch on your repository platform (GitHub or Azure DevOps)

    • Review and merge the pull request to integrate your changes into the main branch

  4. Test Your Changes: Use the built-in testing tools in DynamicWeb 10 or your local environment to ensure your changes work as expected, for example:

    1. Run your project in a local development server (e.g., IIS Express or Kestrel) to preview and verify changes in real-time
    2. Use browser developer tools to debug issues with CSS or JavaScript
    3. If applicable, test integrations with DynamicWeb backend features like the product catalog or content management system

4. Updating the custom project with Swift updates

When new features and bug fixes are released for Swift they are published to the original Swift repository. To incorporate all updates from the Swift repository into your custom project, follow these steps:

  1. Add the Swift Repository as an Upstream Remote

    1. Add the original Swift repository as an upstream remote:

      git remote add upstream https://github.com/dynamicweb/Swift.git

    2. Verify the remotes:

      git remote -v

      Output:

      origin    <Your_Custom_Repo_URL> (fetch)
origin    <Your_Custom_Repo_URL> (push)
upstream  https://github.com/dynamicweb/Swift.git (fetch)
upstream  https://github.com/dynamicweb/Swift.git (push)

  2. Create an Update Branch to handle the updates:

    git checkout -b update-from-upstream

  3. Fetch the latest changes from the Swift Repository:

    git fetch upstream

  4. Merge updates into the update branch:

    1. Merge the changes from the main branch of the upstream repository:

      git merge upstream/main

    2. Resolve any merge conflicts:

      • Open the conflicted files in VS Code (Git highlights them automatically).

      • Resolve the conflicts manually by keeping or modifying changes as needed.

      • Mark resolved files as staged:

        git add <conflicted_file>

    3. Complete the merge:

      git commit

  5. Test the application in the update-from-upstream branch to ensure everything works correctly

  6. Create a pull request to merge updates:

    1. Push the update branch to your custom repository:

      git push origin update-from-upstream

    2. Open your repository on GitHub or Azure DevOps

    3. Create a pull request from update-from-upstream into main

    4. Review and merge the pull request after confirming the changes

5. Pulling specific PRs from the Swift repository

If you want to incorporate a specific bug fix or feature from the original Swift repository without merging all updates, you can cherry-pick a pull request. Follow these steps:

  1. Identify the Pull Request

    • Go to the original Swift repository on GitHub.
    • Locate the pull request you want to incorporate.
    • Note the commit hash associated with the pull request. You can find this in the "Commits" tab of the pull request (e.g., abc1234).

  2. Add the Swift repository as an upstream remote and fetch the latest changes

    git remote add upstream https://github.com/dynamicweb/Swift.git

    git fetch upstream

  3. Cherry-Pick the commit

    • Create a new branch for the changes:

      git checkout -b update-specific-fix

    • Cherry-pick the commit from the pull request (replace <commit-hash> with the actual hash of the commit, e.g. abc1234):

      git cherry-pick <commit-hash>

  4. If conflicts arise during the cherry-pick resolve them

    • Open the conflicted files in VS Code.

    • Resolve conflicts manually.

    • Mark resolved files as staged:

      git add <conflicted_file>

    • Complete the cherry-pick:

      git cherry-pick --continue

  5. Test and push changes

    • Test your changes in the new branch to ensure they work as intended.

    • Push the branch to your custom repository:

      git push origin update-specific-fix

  6. Create a pull request

    • Open your repository on GitHub or Azure DevOps.
    • Create a pull request from update-specific-fix into main.
    • Review and merge the pull request after confirming the changes.

6. Best Practices

  • Use Tags or Branches: Track specific versions of your customizations by using tags or dedicated branches. This ensures you can reference or roll back to previous states if needed. Backup Before Updates: Always create a backup branch of your main branch before merging updates:

    git checkout -b backup-main

  • Frequent Updates: Incorporate upstream updates regularly to avoid large, difficult merges.

  • Document Customizations: Maintain a clear record of your custom changes to simplify conflict resolution.

By following this process, you can efficiently customize the Swift repository and keep your project up to date with the latest features and improvements from the original repository.

Happy coding!

Improve this doc
To top