Merge pull request #365 from freddydk/migrationDocs

Migration docs

README.md

@@ -1,3 +1,4 @@
+# AL-Go for GitHub
 AL-Go for GitHub is a set of GitHub templates and actions, which can be used to setup and maintain professional DevOps processes for your Business Central AL projects.
 
 The goal is that people who have created their GitHub repositories based on the AL-Go templates, can maintain these repositories and stay current just by running a workflow, which updates their repositories. This includes necessary changes to scripts and workflows to cope with new features and functions in Business Central.
@@ -11,7 +12,7 @@ The template repositories to use as starting point are:
 
 The below usage scenarios takes you through how to get started and how to perform the most common tasks.
 
-Usage scenarios:
+## Usage scenarios:
 1. [Create a new per-tenant extension (like AL Go) and start developing in VS Code](Scenarios/GetStarted.md)
 2. [Add a test app to an existing project](Scenarios/AddATestApp.md)
 3. [Register a customer sandbox environment for Continuous Deployment using S2S](Scenarios/RegisterSandboxEnvironment.md)
@@ -29,6 +30,10 @@ Usage scenarios:
 15. [Enabling Telemetry for AL-Go workflows and actions](Scenarios/EnablingTelemetry.md)
 16. [Add a performance test app to an existing project](Scenarios/AddAPerformanceTestApp.md)
 
+## Migration scenarios
+A. [Migrate a repository from Azure DevOps to AL-Go for GitHub without history](MigrateFromAzureDevOpsWithoutHistory.md)<br />
+B. [Migrate a repository from Azure DevOps to AL-Go for GitHub with history](MigrateFromAzureDevOpsWithHistory.md)
+
 **Note:** Please refer to [this description](Scenarios/settings.md) to learn about the settings file and how you can modify default behaviors.
 # This project
 This project in the main source repository for AL-Go for GitHub. This project is deployed on every release to a branch in the following repositories:

Scenarios/MigrateFromAzureDevOpsWithHistory.md

@@ -0,0 +1,59 @@
+# #B Migrate a repository from Azure DevOps to AL-Go for GitHub with history
+*This walkthrough explains how to migrate a repository from Azure DevOps to AL-Go for GitHub **while preserving the full commit history**. As a sample, I will use a repository, which was setup using the CI/CD Hands On Lab, including scripts and pipelines from this.*
+
+*If you do not want to preserve the full commit history, you should use [Scenario A](MigrateFromAzureDevOpsWithoutHistory.md) or [Scenario 11](SetupCiCdForExistingAppSourceApp.md)*
+
+***Note: This walkthrough will leave your existing Azure DevOps repository untouched and you can decide to keep working in that if you like.***
+
+1. Start out by navigating to your **Azure DevOps** repository. Click the **Clone** button and click **Generate Git Credentials**.
+![Azure DevOps](images/b1.png)
+1. Copy the **Password** to the clipboard, navigate to **GitHub**, login and click the small **+** menu in the top right corner and select **Import repository**.
+![files](images/b2.png)
+1. Enter the **GIT URL** to the Azure DevOps repository, choose the owner+name of the new GitHub repository and specify privacy level. Click **Begin Import**.
+![createrepo](images/b3.png)
+1. If your GIT repository requires **authentication**, you will be asked to provide this (the password you copied to the clipboard).
+![auth](images/b4.png)
+1. After GitHub is done importing your repo, you can **navigate to the repo**.
+![importdone](images/b5.png)
+1. In the new GitHub repository, you might see different messages about branches and PRs. This is because GitHub has imported everything. Ignore this for now. Click the **<> Code** button and copy the git address to the clipboard.
+![newrepo](images/b6.png)
+1. Open **VS Code**, press **Ctrl+Shift+P**, select **Git Clone** and paste your git URL into the address bar. Select a location, clone and open the repo and open the Repo in VS Code.
+![clone](images/b7.png)
+1. Delete the files and folders that are not needed in AL-Go for GitHub (including **.github**, **.azureDevOps**, **.pipelines** and **scripts** folders), leaving only your **apps**, your **test apps** and other files you want to preserve.
+![delete](images/b8.png)
+1. Now, download the AL-Go template needed, either the [PTE template](https://github.com/microsoft/AL-Go-PTE/archive/refs/heads/main.zip) or the [AppSource Template](https://github.com/microsoft/AL-Go-AppSource/archive/refs/heads/main.zip). Unpack the .zip file and open the unpacked template files.
+![templatefiles](images/b9.png)
+1. Drag the needed files and folders from the unpacked files file into VS Code (at a minimum the .AL-Go folder and the .github folder) and select to **Copy the folders**.
+![newfiles](images/b10.png)
+1. Modify any settings necessary for the app. Typical settings you might need to modify are:
+    - appFolders, see https://aka.ms/algosettings#appfolders
+    - testFolders, see https://aka.ms/algosettings#testfolders
+    - appSourceMandatoryAffixes, see https://aka.ms/algosettings#appSourceMandatoryAffixes
+    - enableAppSourceCop, see https://aka.ms/algosettings#enableAppSourceCop 
+    - enablePerTenantExtensionCop, see https://aka.ms/algosettings#enablePerTenantExtensionCop
+    - enableCodeCop, see https://aka.ms/algosettings#enableCodeCop
+    - enableUICop, see https://aka.ms/algosettings#enableUICop
+    - rulesetFile, see https://aka.ms/algosettings#rulesetFile
+    - runNumberOffset, see https://aka.ms/algosettings#runNumberOffset
+
+    Also, if you are migrating an AppSource App, you will need to create a secret called LicenseFileUrl, which should contain a secure direct download URL to your license file, as mentioned [here](SetupCiCdForExistingAppSourceApp.md).
+
+    Finally, if you want AL-Go for GitHub to digitally sign your file, you need to create two secrets in the repository (or in the organization) called **CodeSignCertificateUrl** and **CodeSignCertificatePassword**, being a secure direct download URL to your PFX certificate and the PFX password for the certificate.
+
+    See a list of all settings [here](settings.md).
+
+1. In VS Code, in the Source Control area, **Add** all changed files, **Commit** the changes and press **Sync Changes** to push to GitHub.
+![commit](images/b11.png)
+1. Navigate back to your repository on GitHub. See that your files have been uploaded. Click **Settings** -> **Actions** -> **General**, select **Allow all actions and reusable workflows** and click **Save**.
+![upload](images/b12.png)
+1. Click **Actions**, select the **CI/CD** workflow and click **Run workflow** to manually run the CI/CD workflow.
+![cicd](images/b13.png)
+1. Open the running workflow to see **status and summary** and **wait for the build to complete**.
+![success](images/b14.png)
+1. Scroll down to see the artifacts and the **test results**
+![testresults](images/b15.png)
+1. Navigate to **Code** and click **Commits** to see the history and all your commits.
+![history](images/b16.png)
+
+---
+[back](../README.md)

Scenarios/MigrateFromAzureDevOpsWithoutHistory.md

@@ -0,0 +1,49 @@
+# #A Migrate a repository from Azure DevOps to AL-Go for GitHub without history
+*This walkthrough explains how to migrate a repository from Azure DevOps to AL-Go for GitHub **without including the commit history**. As a sample, I will use a repository, which was setup using the CI/CD Hands On Lab, including scripts and pipelines from this.*
+
+*This walkthrough is similar to [scenario 11](SetupCiCdForExistingAppSourceApp.md), but uses VS Code and File Explorer to move the files instead of uploading a .zip file.*
+
+***Note: This walkthrough will leave your existing Azure DevOps repository untouched and you can decide to keep working in that if you like.***
+
+1. Start out by navigating to your **Azure DevOps** repository. Click the **Clone** button.
+![Azure DevOps](images/a1.png)
+1. Clone the repository to your PC by selecting Clone in **VS Code** (or your favorite way of cloning). And open the files in the **file explorer**.
+![files](images/a2.png)
+1. Navigate to [https://aka.ms/algopte](https://aka.ms/algopte) or [https://aka.ms/algoappsource](https://aka.ms/algoappsource), click **Use this template**. Select **Create a new repository** and choose the owner + name of the repository and select public or private. Click **Create repository from template** and open the repository.
+![createrepo](images/a3.png)
+1. In the new repository, click the **<> Code** button and copy the git address to the clipboard. Open VS Code, press Ctrl+Shift+P, select **Git Clone** and paste your git URL into the address bar. Select a location, clone and open the repo and navigate to the File Explorer with the **Azure DevOps cloned files**.
+![clone](images/a4.png)
+1. In the file Explorer containing the cloned files from the Azure DevOps repo, select all the folders containing apps, test apps or other files you need to migrate over. Do not include the **.git**, **.github**, **.azureDevOps**, **.pipelines** and **scripts** folders - we won't be using them. Drag the files to VS Code and select **Copy Folders**
+![copy](images/a5.png)
+1. Modify any settings necessary for the app. Typical settings you might need to modify are:
+    - appFolders, see https://aka.ms/algosettings#appfolders
+    - testFolders, see https://aka.ms/algosettings#testfolders
+    - appSourceMandatoryAffixes, see https://aka.ms/algosettings#appSourceMandatoryAffixes
+    - enableAppSourceCop, see https://aka.ms/algosettings#enableAppSourceCop 
+    - enablePerTenantExtensionCop, see https://aka.ms/algosettings#enablePerTenantExtensionCop
+    - enableCodeCop, see https://aka.ms/algosettings#enableCodeCop
+    - enableUICop, see https://aka.ms/algosettings#enableUICop
+    - rulesetFile, see https://aka.ms/algosettings#rulesetFile
+    - runNumberOffset, see https://aka.ms/algosettings#runNumberOffset
+
+    Also, if you are migrating an AppSource App, you will need to create a secret called LicenseFileUrl, which should contain a secure direct download URL to your license file, as mentioned [here](SetupCiCdForExistingAppSourceApp.md).
+
+    Finally, if you want AL-Go for GitHub to digitally sign your file, you need to create two secrets in the repository (or in the organization) called **CodeSignCertificateUrl** and **CodeSignCertificatePassword**, being a secure direct download URL to your PFX certificate and the PFX password for the certificate.
+
+    See a list of all settings [here](settings.md).
+
+1. In VS Code, in the Source Control area, **Add** all changed files, **Commit** the changes and press **Sync Changes** to push to GitHub.
+![commit](images/a6.png)
+1. Navigate back to your repository on GitHub. See that your files have been uploaded.
+![upload](images/a7.png)
+1. Click **Actions** to see that the **CI/CD** workflow was kicked off with your migration files.
+![cicd](images/a8.png)
+1. Open the running workflow to see **status and summary** and wait for the build to complete.
+![success](images/a9.png)
+1. Scroll down to see the **artifacts** and the **test results**.
+![testresults](images/a10.png)
+1. Navigate to **Code** and click **Commits** to see the history.
+![history](images/a11.png)
+
+---
+[back](../README.md)

Scenarios/settings.md

@@ -22,9 +22,9 @@ When running a workflow or a local script, the settings are applied by reading o
 | :-- | :-- | :-- |
 | <a id="country"></a>country | Specifies which country this app is built against. | us |
 | <a id="repoVersion"></a>repoVersion | RepoVersion is the repository version number. The Repo Version number consists of \<major\>.\<minor\> only and is used for naming build artifacts in the CI/CD workflow. Build artifacts are named **\<project\>-Apps-\<repoVersion\>.\<build\>.\<revision\>** and can contain multiple apps. The Repo Version number is used as major.minor for individual apps if versioningStrategy is +16. | 1.0 |
-| <a id="appFolders"></a>appFolders | appFolders should be an array of folders (relative to project root), which contains apps for this project. Apps in these folders are sorted based on dependencies and built and published in that order. | [ ] |
-| <a id="testFolders"></a>testFolders | testFolders should be an array of folders (relative to project root), which contains test apps for this project. Apps in these folders are sorted based on dependencies and built, published and tests are run in that order. | [ ] |
-| <a id="bcptTestFolders"></a>bcptTestFolders | bcptTestFolders should be an array of folders (relative to project root), which contains performance test apps for this project. Apps in these folders are sorted based on dependencies and built, published and bcpt tests are run in that order. | [ ] |
+| <a id="appFolders"></a>appFolders | appFolders should be an array of folders (relative to project root), which contains apps for this project. Apps in these folders are sorted based on dependencies and built and published in that order.<br />If appFolders are not specified, AL-Go for GitHub will try to locate appFolders in the root of the project. | [ ] |
+| <a id="testFolders"></a>testFolders | testFolders should be an array of folders (relative to project root), which contains test apps for this project. Apps in these folders are sorted based on dependencies and built, published and tests are run in that order.<br />If testFolders are not specified, AL-Go for GitHub will try to locate testFolders in the root of the project. | [ ] |
+| <a id="bcptTestFolders"></a>bcptTestFolders | bcptTestFolders should be an array of folders (relative to project root), which contains performance test apps for this project. Apps in these folders are sorted based on dependencies and built, published and bcpt tests are run in that order.<br />If bcptTestFolders are not specified, AL-Go for GitHub will try to locate bcptTestFolders in the root of the project. | [ ] |
 | <a id="appDependencyProbingPaths"></a>appDependencyProbingPaths | Array of dependency specifications, from which apps will be downloaded when the CI/CD workflow is starting. Every dependency specification consists of the following properties:<br />**repo** = repository<br />**version** = version (default latest)<br />**release_status** = latestBuild/release/prerelease/draft (default release)<br />**projects** = projects (default * = all)<br />**AuthTokenSecret** = Name of secret containing auth token (default none)<br /> | [ ] |
 | <a id="environments"></a>environments | Array of logical environment names. You can specify environments in GitHub environments or in the repo settings file. If you specify environments in the settings file, you can create your AUTHCONTEXT secret using **&lt;environmentname&gt;_AUTHCONTEXT**. If the actual environment name is different from the logical environmentname, then you can create a secret with the actual name called **&lt;environmentname&gt;_ENVIRONMENTNAME** | [ ] |
 | <a id="cleanModePreprocessorSymbols"></a>cleanModePreprocessorSymbols | List of clean tags to be used in _Clean_ build mode | [ ] |