rthomas320 commented on code in PR #1180: URL: https://github.com/apache/daffodil-vscode/pull/1180#discussion_r1983289747
########## DEVELOPMENT.md: ########## @@ -66,13 +243,238 @@ You can then take this .vsix file and install the extension into your vscode ins  +#### Automated Testing Suite + +The Apache Daffodil VS Code Extension comes with an automated test suite. Run it as follows: + +```shell +yarn test +``` + +##### Testing Against a Specific Version of VS Code + +By default, the test suite will use the earliest supported release of VS Code. To test against any _specific_ version of VS Code (in this example, VS Code version 1.74.3), execute the test suite as follows, setting `DAFFODIL_TEST_VSCODE_VERSION` to the desired version: + +```shell +DAFFODIL_TEST_VSCODE_VERSION=1.74.3 yarn test +``` + +Set `DAFFODIL_TEST_VSCODE_VERSION` to `stable` to use the latest stable release, or to `insiders` to use the latest (nightly) insiders build. + + +### Debugging the Extension + +Create a `sampleWorkspace` folder in the folder one level higher than where `daffodil-vscode` currently resides. For example, if you have your `daffodil-vscode` folder stored in a folder called repos, then make a folder in repos called `sampleWorkspace`. + + + +It’s advised to copy sample data files and sample DFDL schemas (.dfdl.xsd) in here. You can find DFDL schemas at [DFDL Schemas for Commercial and Scientific Data Formats](https://github.com/DFDLSchemas). + +Optional: If you would like to recompile the code when you're editing, run `yarn watch` before following the next steps. More information is outlined in [Automatically Recompile Code When it Changes](#automatically-recompile-code-when-it-changes) + +Next start debugging the extension. Make sure the “Extension” debug configuration is currently selected. You can press the green run button or alternatively press F5. + + + +You may see this window pop up + + + +Click on debug anyway once yarn watch says webpack is fully compiled. + + + +A new VSCode window should’ve popped up with the sampleWorkspace opened. + + + +Open the command palette with `Ctrl + Shift + P` and type in `Daffodil Debug`. Select the `Configure launch.json` option. + + + +Your window should look like this. + + + +Scroll down and check these following options + + + +Click save + + + +Click on the Run and Debug Icon. Wizard Config should show at the top. + + + +Then select a schema file and a data file. (Note, if you want to hard code where the images are, you’re able to change the DFDL and data file path in the Daffodil Configure launch.json window) + + + + + +Your window should look like the following. Note that you may have to move some tabs around. + + + +Here’s an example view of the data editor (OmegaEdit) with the schema on the left. + + + +Here’s the infoset diff view. The infoset is the resulting output XML/JSON file. + + + +#### Changing the sampleWorkspace folder name and location +If you would like to specify a different name and/or location for the sampleWorkspace is, modify the following line in `.vscode/launch.json`: Review Comment: Consider changing "If you would like to specify a different name and/or location for the sampleWorkspace is" to "If you would like to specify a different name and/or location for the sampleWorkspace" ########## DEVELOPMENT.md: ########## @@ -15,38 +15,215 @@ limitations under the License. --> -# Welcome -If you would like the latest stable release of the extension, please reference the README.md for instructions on how to retrieve that. -You can download a zip archive of the source code for the extension. You can extract this to any directory of your choice and open it within vscode to begin poking around. +# Daffodil-VSCode Developer's Guide -The project currently has many components and is growing, please refer to the wiki for an overview of what the extension includes. There is also user documentation on the right side with additional release specific use case guides. Here is the one for v1.3.1: -https://github.com/apache/daffodil-vscode/wiki/Apache-Daffodil%E2%84%A2-Extension-for-Visual-Studio-Code:-v1.3.1 +## Build Status + +[](https://github.com/apache/daffodil-vscode/actions/workflows/CI.yml) +[](https://github.com/apache/daffodil-vscode/actions/workflows/nightly.yml) + +## Table of Contents + +- [Daffodil-VSCode Developer's Guide](#daffodil-vscode-developers-guide) + * [Build Status](#build-status) + * [Table of Contents](#table-of-contents) + * [Welcome](#welcome) + * [Prerequisites ](#prerequisites) + + [Install Git](#install-git) + + [Install Visual Studio Code (VSCode)](#install-visual-studio-code-vscode) + * [Installing Build Requirements](#installing-build-requirements) + + [Summary of Build Requirements](#summary-of-build-requirements) + + [Step-by-step Guide for Installing Build Requirements](#step-by-step-guide-for-installing-build-requirements) + - [Installing Node](#installing-node) + * [Installing Node on Windows Note ](#installing-node-on-windows-note) + - [Installing Java (JDK 17)](#installing-java-jdk-17) + * [Build Issues with Higher JDK Versions ](#build-issues-with-higher-jdk-versions) + * [Switching Java Versions on Linux](#switching-java-versions-on-linux) + - [Installing SBT](#installing-sbt) + - [Enabling Yarn from Within Node](#enabling-yarn-from-within-node) + * [Do Not Use the Latest Version of Yarn](#do-not-use-the-latest-version-of-yarn) + * [How to Enable](#how-to-enable) + * [Contributing and Setup](#contributing-and-setup) + + [Forking the Project](#forking-the-project) + + [Cloning the Project to Local Environment](#cloning-the-project-to-local-environment) + - [Setting up SSH Keys](#setting-up-ssh-keys) + + [General Workflow](#general-workflow) + + [Opening the Repository in VSCode](#opening-the-repository-in-vscode) + - [Recommended VSCode Extensions](#recommended-vscode-extensions) + - [Required VSCode Extensions](#required-vscode-extensions) + + [Verifying Setup Can Build](#verifying-setup-can-build) + - [Yarn Package](#yarn-package) + - [Automated Testing Suite](#automated-testing-suite) + * [Testing Against a Specific Version of VS Code](#testing-against-a-specific-version-of-vs-code) + + [Debugging the Extension](#debugging-the-extension) + - [Changing the sampleWorkspace folder name and location](#changing-the-sampleworkspace-folder-name-and-location) + - [Test a Local Version of Apache Daffodil Debugge](#test-a-local-version-of-apache-daffodil-debugge) + - [Automatically Recompile Code When it Changes](#automatically-recompile-code-when-it-changes) + + [Troubleshooting](#troubleshooting) + - [Yarn Package Issues](#yarn-package-issues) + * [If Yarn Keeps Updating to The Latest Version](#if-yarn-keeps-updating-to-the-latest-version) + - [Yarn Test Issues](#yarn-test-issues) + * [Data Editor Opens Test Case Failing](#data-editor-opens-test-case-failing) + * [TLS Certificate Issues](#tls-certificate-issues) + - [Debugging Issues](#debugging-issues) + * [SELinux Port Functionality](#selinux-port-functionality) + * [Windows Yarn Test Window Not Loading Extensions](#windows-yarn-test-window-not-loading-extensions) + - [Re-trying Verification After Errors](#re-trying-verification-after-errors) + * [Building the Documentation](#building-the-documentation) + + [Install Pandoc](#install-pandoc) + + [Command to build the Documentation](#command-to-build-the-documentation) + * [Reviewing and Verifying Dependency Bot Updates](#reviewing-and-verifying-dependency-bot-updates) + * [Testing Information](#testing-information) + * [Monitoring Project Status](#monitoring-project-status) + * [Thank you for your interest in contributing to this project!](#thank-you-for-your-interest-in-contributing-to-this-project) + +## Welcome + +This guide contains developer-oriented instructions on how to setup your local development environment for contributing to this project. + +If you would like the latest stable release of the extension, please reference the [README file](README.md). + +The project is currently growing, please refer to the [wiki](https://github.com/apache/daffodil-vscode/wiki) for an overview of what the extension includes. There is also user documentation on the right pane with release specific use case guides. + +## Prerequisites + +### Install Git +If your system doesn’t have Git installed, [install Git](https://git-scm.com/downloads). Select the appropriate operating system and follow the listed instructions. +To verify git is installed on your system, enter git -v into your system’s terminal and it should display the version of git if properly installed. + +### Install Visual Studio Code (VSCode) + +Install VSCode per [official VSCode documentation](https://code.visualstudio.com/docs/setup/setup-overview): +* [Windows](https://code.visualstudio.com/docs/setup/windows) +* [Linux](https://code.visualstudio.com/docs/setup/linux) +* [MacOS](https://code.visualstudio.com/docs/setup/mac) + +## Installing Build Requirements +This section will provide describe what requirements are needed to build with a step-by-step guide to assist developers of varying skill levels. The steps provide recommended methods for installing build requirements, but don't have to be followed exactly one-to-one. + Review Comment: This sentence needs to be modified: This section will provide describe what requirements are needed to build with a step-by-step guide to assist developers of varying skill levels. ########## DEVELOPMENT.md: ########## @@ -15,38 +15,215 @@ limitations under the License. --> -# Welcome -If you would like the latest stable release of the extension, please reference the README.md for instructions on how to retrieve that. -You can download a zip archive of the source code for the extension. You can extract this to any directory of your choice and open it within vscode to begin poking around. +# Daffodil-VSCode Developer's Guide -The project currently has many components and is growing, please refer to the wiki for an overview of what the extension includes. There is also user documentation on the right side with additional release specific use case guides. Here is the one for v1.3.1: -https://github.com/apache/daffodil-vscode/wiki/Apache-Daffodil%E2%84%A2-Extension-for-Visual-Studio-Code:-v1.3.1 +## Build Status + +[](https://github.com/apache/daffodil-vscode/actions/workflows/CI.yml) +[](https://github.com/apache/daffodil-vscode/actions/workflows/nightly.yml) + +## Table of Contents + +- [Daffodil-VSCode Developer's Guide](#daffodil-vscode-developers-guide) + * [Build Status](#build-status) + * [Table of Contents](#table-of-contents) + * [Welcome](#welcome) + * [Prerequisites ](#prerequisites) + + [Install Git](#install-git) + + [Install Visual Studio Code (VSCode)](#install-visual-studio-code-vscode) + * [Installing Build Requirements](#installing-build-requirements) + + [Summary of Build Requirements](#summary-of-build-requirements) + + [Step-by-step Guide for Installing Build Requirements](#step-by-step-guide-for-installing-build-requirements) + - [Installing Node](#installing-node) + * [Installing Node on Windows Note ](#installing-node-on-windows-note) + - [Installing Java (JDK 17)](#installing-java-jdk-17) + * [Build Issues with Higher JDK Versions ](#build-issues-with-higher-jdk-versions) + * [Switching Java Versions on Linux](#switching-java-versions-on-linux) + - [Installing SBT](#installing-sbt) + - [Enabling Yarn from Within Node](#enabling-yarn-from-within-node) + * [Do Not Use the Latest Version of Yarn](#do-not-use-the-latest-version-of-yarn) + * [How to Enable](#how-to-enable) + * [Contributing and Setup](#contributing-and-setup) + + [Forking the Project](#forking-the-project) + + [Cloning the Project to Local Environment](#cloning-the-project-to-local-environment) + - [Setting up SSH Keys](#setting-up-ssh-keys) + + [General Workflow](#general-workflow) + + [Opening the Repository in VSCode](#opening-the-repository-in-vscode) + - [Recommended VSCode Extensions](#recommended-vscode-extensions) + - [Required VSCode Extensions](#required-vscode-extensions) + + [Verifying Setup Can Build](#verifying-setup-can-build) + - [Yarn Package](#yarn-package) + - [Automated Testing Suite](#automated-testing-suite) + * [Testing Against a Specific Version of VS Code](#testing-against-a-specific-version-of-vs-code) + + [Debugging the Extension](#debugging-the-extension) + - [Changing the sampleWorkspace folder name and location](#changing-the-sampleworkspace-folder-name-and-location) + - [Test a Local Version of Apache Daffodil Debugge](#test-a-local-version-of-apache-daffodil-debugge) + - [Automatically Recompile Code When it Changes](#automatically-recompile-code-when-it-changes) + + [Troubleshooting](#troubleshooting) + - [Yarn Package Issues](#yarn-package-issues) + * [If Yarn Keeps Updating to The Latest Version](#if-yarn-keeps-updating-to-the-latest-version) + - [Yarn Test Issues](#yarn-test-issues) + * [Data Editor Opens Test Case Failing](#data-editor-opens-test-case-failing) + * [TLS Certificate Issues](#tls-certificate-issues) + - [Debugging Issues](#debugging-issues) + * [SELinux Port Functionality](#selinux-port-functionality) + * [Windows Yarn Test Window Not Loading Extensions](#windows-yarn-test-window-not-loading-extensions) + - [Re-trying Verification After Errors](#re-trying-verification-after-errors) + * [Building the Documentation](#building-the-documentation) + + [Install Pandoc](#install-pandoc) + + [Command to build the Documentation](#command-to-build-the-documentation) + * [Reviewing and Verifying Dependency Bot Updates](#reviewing-and-verifying-dependency-bot-updates) + * [Testing Information](#testing-information) + * [Monitoring Project Status](#monitoring-project-status) + * [Thank you for your interest in contributing to this project!](#thank-you-for-your-interest-in-contributing-to-this-project) + +## Welcome + +This guide contains developer-oriented instructions on how to setup your local development environment for contributing to this project. + +If you would like the latest stable release of the extension, please reference the [README file](README.md). + +The project is currently growing, please refer to the [wiki](https://github.com/apache/daffodil-vscode/wiki) for an overview of what the extension includes. There is also user documentation on the right pane with release specific use case guides. + +## Prerequisites + +### Install Git +If your system doesn’t have Git installed, [install Git](https://git-scm.com/downloads). Select the appropriate operating system and follow the listed instructions. +To verify git is installed on your system, enter git -v into your system’s terminal and it should display the version of git if properly installed. + +### Install Visual Studio Code (VSCode) + +Install VSCode per [official VSCode documentation](https://code.visualstudio.com/docs/setup/setup-overview): +* [Windows](https://code.visualstudio.com/docs/setup/windows) +* [Linux](https://code.visualstudio.com/docs/setup/linux) +* [MacOS](https://code.visualstudio.com/docs/setup/mac) + +## Installing Build Requirements +This section will provide describe what requirements are needed to build with a step-by-step guide to assist developers of varying skill levels. The steps provide recommended methods for installing build requirements, but don't have to be followed exactly one-to-one. + +### Summary of Build Requirements + +- Java Development Kit (JDK) 17 or lower, but higher than or equal to 8 +- SBT 0.13.8 or higher +- Node 16 or higher +- [Yarn Classic](https://classic.yarnpkg.com/en/docs/install#windows-stable) + +### Step-by-step Guide for Installing Build Requirements + +#### Installing Node +Navigate to the [Node Download page](https://nodejs.org/en/download). Select the instructions for installing the latest LTS version of Node.js for your operating system using fnm with npm. + + +##### Installing Node on Windows Note +Make sure you have `winget` installed. If it’s not installed, you can install it by typing in `Install-Module -Name Microsoft.WinGet.Client` into PowerShell. +After following all the steps outlined on Node’s page, you want to [create a PowerShell profile](https://lazyadmin.nl/powershell/powershell-profile/) which is a PowerShell script that gets executed every time a new instance of PowerShell is opened. Then append `fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression` per [fnm's guidance](https://github.com/Schniz/fnm?tab=readme-ov-file#powershell). + +#### Installing Java (JDK 17) +You can install [Oracle's JDK 17](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) or alternatively install the OpenJDK equivalent. + +##### Build Issues with Higher JDK Versions +Note that higher versions of the JDK may cause extension building issues and is not advised. + +##### Switching Java Versions on Linux +You might have Java already installed. You can change the default Java provider and version by running `sudo update-alternatives --config java`. + +#### Installing SBT +Install SBT for your appropriate operating system: +* [Windows Instructions](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html) + * Preferable method: install via .msi +* [Linux Instructions](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html) +* [MacOS Instructions](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Mac.html) + +#### Enabling Yarn from Within Node + +##### Do Not Use the Latest Version of Yarn +Do not upgrade versions of Yarn for repository. Do not follow the [instructions on Yarn’s official website](https://yarnpkg.com/getting-started/install). This will break the extension packaging process. +##### How to Enable +Type into the console `corepack enable yarn`. + +## Contributing and Setup + +### Forking the Project -## Contributing Due to this being an Apache project, if you would like to contribute, you will need to fork the daffodil-vscode main branch to your own repo of choice and create pull requests to the main branch with your code changes.  - -Once forked, you can clone that forked repository to your own local environment. This can be done by using `git clone`, followed by copy and pasting the https or ssh urls shown under the “Code” dropdown. -  + +### Cloning the Project to Local Environment +Once forked, you can clone that forked repository to your own local environment. This can be done by using `git clone`, followed by copy and pasting the https or SSH urls shown under the “Code” dropdown. We recommend using SSH. Instructions for setting up SSH can be found in [Setting up SSH Keys](#setting-up-ssh-keys). + +  -If you have not setup your ssh keys for github, you can follow this guide here: https://docs.github.com/en/authentication/connecting-to-github-with-ssh. Or you can use https or another method of your choice. +Once cloned, you can now create branches, commits, and push changes back to your remote fork. You may make changes with any IDE, but we highly encourage using VSCode for testing for maximum compatability. + +#### Setting up SSH Keys +Enter ssh-keygen into your terminal to generate an RSA key. Follow the prompts for naming the public and private key files (optional) and giving the keys an optional passphrase. + +The public and private keys are stored in a folder called .ssh in your users folder. The public key file is denoted with a .pub whereas the private key doesn’t have a file extension. + +Navigate to [SSH and GPG keys GitHub settings](https://github.com/settings/keys). Log into your GitHub account if needed. Click on New SSH Key. + + -Once cloned, you can now create branches, commits, and push changes back to your remote fork. You may make changes with any IDE, but because the extension is built for vscode, we recommend using that to maximize testing ability. +Give your new SSH Key a name and paste the contents of the .pub file into the key textbox + + +Note that the above image has parts of the key blurred out for confidentiality. + +Click on Add SSH key and follow GitHub prompts for verification. + +[GitHub has their own guide on setting up SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) which can be alternatively followed. + +### General Workflow Ensure that you keep your fork synced with the daffodil-vscode main by using the sync fork button, this ensures that you are developing with up to date code, so that you can be sure your changes work with present code.  - If any changes were made while you were working on yours, you will need to pull these changes down to your local environment and merge them with your changes before pushing back to remote. Once changes are pushed, you can make pull requests with completed changes back to the main daffodil-vscode branch. You can use the contribute drop down to create a pull request back to the main branch.  -## Building +### Opening the Repository in VSCode + +There are multiple ways of opening the repository that you have cloned in VSCode: + +1. In a terminal, type in `code <PATH TO THE CLONED REPOSITORY>` +2. Clicking on open folder at the VSCode homescreen + + + +3. At the top options bar, File -> Open Folder + + + +#### Recommended VSCode Extensions +Upon opening, VSCode may prompt you to install recommended extensions. Go ahead and accept installing the recommended extensions. +* [Prettier - Code formatter - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) + +#### Required VSCode Extensions +Daffodil-VSCode depends on the following extensions +* [JAR Viewer - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=wmanth.jar-viewer) +* [Highlight Matching Tag - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=vincaslt.highlight-matching-tag) + + +### Verifying Setup Can Build +Navigate inside your cloned folder in a terminal. Enter `yarn` to install required packages. If it prompts you to install yarn 1.22.XX, type `y`. + +Then type in `yarn package`. If there’s new .vsix file in the folder, then you have successfully set up your development environment correctly. For more information about `yarn package`, read [Yarn Package](#yarn-package). + + + +Lastly, run `yarn test`. All tests should pass without any errors. More information can be found under [Automated Testing Suite (Yarn Test)](#automated-testing-suite) + + + +Alternatively, you can run all of the commands in a single line by running `yarn && yarn package && yarn test && echo "All good!"`. + +#### Yarn Package If you would like to build to confirm that your changes compile, you can run the extension through the vscode debugger as shown below. Under the run and debugger, you should see a launch.json already loaded for the extension, just hit the green play button. This will open a new debug window of vscode that will have the extension built and running. You can then test any changes made and ensure it is operating as intended. Review Comment: I see that you supply the information about the popup message further down in the document. So it probably isn't needed here. Maybe the information about debugging should be moved to below? ########## DEVELOPMENT.md: ########## @@ -66,13 +243,238 @@ You can then take this .vsix file and install the extension into your vscode ins  +#### Automated Testing Suite + +The Apache Daffodil VS Code Extension comes with an automated test suite. Run it as follows: + +```shell +yarn test +``` + +##### Testing Against a Specific Version of VS Code + +By default, the test suite will use the earliest supported release of VS Code. To test against any _specific_ version of VS Code (in this example, VS Code version 1.74.3), execute the test suite as follows, setting `DAFFODIL_TEST_VSCODE_VERSION` to the desired version: + +```shell +DAFFODIL_TEST_VSCODE_VERSION=1.74.3 yarn test +``` + +Set `DAFFODIL_TEST_VSCODE_VERSION` to `stable` to use the latest stable release, or to `insiders` to use the latest (nightly) insiders build. + + +### Debugging the Extension + +Create a `sampleWorkspace` folder in the folder one level higher than where `daffodil-vscode` currently resides. For example, if you have your `daffodil-vscode` folder stored in a folder called repos, then make a folder in repos called `sampleWorkspace`. + + + +It’s advised to copy sample data files and sample DFDL schemas (.dfdl.xsd) in here. You can find DFDL schemas at [DFDL Schemas for Commercial and Scientific Data Formats](https://github.com/DFDLSchemas). + +Optional: If you would like to recompile the code when you're editing, run `yarn watch` before following the next steps. More information is outlined in [Automatically Recompile Code When it Changes](#automatically-recompile-code-when-it-changes) + +Next start debugging the extension. Make sure the “Extension” debug configuration is currently selected. You can press the green run button or alternatively press F5. + + + +You may see this window pop up + + + +Click on debug anyway once yarn watch says webpack is fully compiled. + + + +A new VSCode window should’ve popped up with the sampleWorkspace opened. + + + +Open the command palette with `Ctrl + Shift + P` and type in `Daffodil Debug`. Select the `Configure launch.json` option. + + + +Your window should look like this. + + + +Scroll down and check these following options + + + +Click save + + + +Click on the Run and Debug Icon. Wizard Config should show at the top. + + + +Then select a schema file and a data file. (Note, if you want to hard code where the images are, you’re able to change the DFDL and data file path in the Daffodil Configure launch.json window) Review Comment: Consider changing "if you want to hard code where the images are," to "if you want to hard code where the files are," ########## DEVELOPMENT.md: ########## @@ -15,38 +15,215 @@ limitations under the License. --> -# Welcome -If you would like the latest stable release of the extension, please reference the README.md for instructions on how to retrieve that. -You can download a zip archive of the source code for the extension. You can extract this to any directory of your choice and open it within vscode to begin poking around. +# Daffodil-VSCode Developer's Guide -The project currently has many components and is growing, please refer to the wiki for an overview of what the extension includes. There is also user documentation on the right side with additional release specific use case guides. Here is the one for v1.3.1: -https://github.com/apache/daffodil-vscode/wiki/Apache-Daffodil%E2%84%A2-Extension-for-Visual-Studio-Code:-v1.3.1 +## Build Status + +[](https://github.com/apache/daffodil-vscode/actions/workflows/CI.yml) +[](https://github.com/apache/daffodil-vscode/actions/workflows/nightly.yml) + +## Table of Contents + +- [Daffodil-VSCode Developer's Guide](#daffodil-vscode-developers-guide) + * [Build Status](#build-status) + * [Table of Contents](#table-of-contents) + * [Welcome](#welcome) + * [Prerequisites ](#prerequisites) + + [Install Git](#install-git) + + [Install Visual Studio Code (VSCode)](#install-visual-studio-code-vscode) + * [Installing Build Requirements](#installing-build-requirements) + + [Summary of Build Requirements](#summary-of-build-requirements) + + [Step-by-step Guide for Installing Build Requirements](#step-by-step-guide-for-installing-build-requirements) + - [Installing Node](#installing-node) + * [Installing Node on Windows Note ](#installing-node-on-windows-note) + - [Installing Java (JDK 17)](#installing-java-jdk-17) + * [Build Issues with Higher JDK Versions ](#build-issues-with-higher-jdk-versions) + * [Switching Java Versions on Linux](#switching-java-versions-on-linux) + - [Installing SBT](#installing-sbt) + - [Enabling Yarn from Within Node](#enabling-yarn-from-within-node) + * [Do Not Use the Latest Version of Yarn](#do-not-use-the-latest-version-of-yarn) + * [How to Enable](#how-to-enable) + * [Contributing and Setup](#contributing-and-setup) + + [Forking the Project](#forking-the-project) + + [Cloning the Project to Local Environment](#cloning-the-project-to-local-environment) + - [Setting up SSH Keys](#setting-up-ssh-keys) + + [General Workflow](#general-workflow) + + [Opening the Repository in VSCode](#opening-the-repository-in-vscode) + - [Recommended VSCode Extensions](#recommended-vscode-extensions) + - [Required VSCode Extensions](#required-vscode-extensions) + + [Verifying Setup Can Build](#verifying-setup-can-build) + - [Yarn Package](#yarn-package) + - [Automated Testing Suite](#automated-testing-suite) + * [Testing Against a Specific Version of VS Code](#testing-against-a-specific-version-of-vs-code) + + [Debugging the Extension](#debugging-the-extension) + - [Changing the sampleWorkspace folder name and location](#changing-the-sampleworkspace-folder-name-and-location) + - [Test a Local Version of Apache Daffodil Debugge](#test-a-local-version-of-apache-daffodil-debugge) + - [Automatically Recompile Code When it Changes](#automatically-recompile-code-when-it-changes) + + [Troubleshooting](#troubleshooting) + - [Yarn Package Issues](#yarn-package-issues) + * [If Yarn Keeps Updating to The Latest Version](#if-yarn-keeps-updating-to-the-latest-version) + - [Yarn Test Issues](#yarn-test-issues) + * [Data Editor Opens Test Case Failing](#data-editor-opens-test-case-failing) + * [TLS Certificate Issues](#tls-certificate-issues) + - [Debugging Issues](#debugging-issues) + * [SELinux Port Functionality](#selinux-port-functionality) + * [Windows Yarn Test Window Not Loading Extensions](#windows-yarn-test-window-not-loading-extensions) + - [Re-trying Verification After Errors](#re-trying-verification-after-errors) + * [Building the Documentation](#building-the-documentation) + + [Install Pandoc](#install-pandoc) + + [Command to build the Documentation](#command-to-build-the-documentation) + * [Reviewing and Verifying Dependency Bot Updates](#reviewing-and-verifying-dependency-bot-updates) + * [Testing Information](#testing-information) + * [Monitoring Project Status](#monitoring-project-status) + * [Thank you for your interest in contributing to this project!](#thank-you-for-your-interest-in-contributing-to-this-project) + +## Welcome + +This guide contains developer-oriented instructions on how to setup your local development environment for contributing to this project. + +If you would like the latest stable release of the extension, please reference the [README file](README.md). + +The project is currently growing, please refer to the [wiki](https://github.com/apache/daffodil-vscode/wiki) for an overview of what the extension includes. There is also user documentation on the right pane with release specific use case guides. + +## Prerequisites + +### Install Git +If your system doesn’t have Git installed, [install Git](https://git-scm.com/downloads). Select the appropriate operating system and follow the listed instructions. +To verify git is installed on your system, enter git -v into your system’s terminal and it should display the version of git if properly installed. + +### Install Visual Studio Code (VSCode) + +Install VSCode per [official VSCode documentation](https://code.visualstudio.com/docs/setup/setup-overview): +* [Windows](https://code.visualstudio.com/docs/setup/windows) +* [Linux](https://code.visualstudio.com/docs/setup/linux) +* [MacOS](https://code.visualstudio.com/docs/setup/mac) + +## Installing Build Requirements +This section will provide describe what requirements are needed to build with a step-by-step guide to assist developers of varying skill levels. The steps provide recommended methods for installing build requirements, but don't have to be followed exactly one-to-one. + +### Summary of Build Requirements + +- Java Development Kit (JDK) 17 or lower, but higher than or equal to 8 +- SBT 0.13.8 or higher +- Node 16 or higher +- [Yarn Classic](https://classic.yarnpkg.com/en/docs/install#windows-stable) + +### Step-by-step Guide for Installing Build Requirements + +#### Installing Node +Navigate to the [Node Download page](https://nodejs.org/en/download). Select the instructions for installing the latest LTS version of Node.js for your operating system using fnm with npm. + + +##### Installing Node on Windows Note +Make sure you have `winget` installed. If it’s not installed, you can install it by typing in `Install-Module -Name Microsoft.WinGet.Client` into PowerShell. +After following all the steps outlined on Node’s page, you want to [create a PowerShell profile](https://lazyadmin.nl/powershell/powershell-profile/) which is a PowerShell script that gets executed every time a new instance of PowerShell is opened. Then append `fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression` per [fnm's guidance](https://github.com/Schniz/fnm?tab=readme-ov-file#powershell). + +#### Installing Java (JDK 17) +You can install [Oracle's JDK 17](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) or alternatively install the OpenJDK equivalent. + +##### Build Issues with Higher JDK Versions +Note that higher versions of the JDK may cause extension building issues and is not advised. + +##### Switching Java Versions on Linux +You might have Java already installed. You can change the default Java provider and version by running `sudo update-alternatives --config java`. + +#### Installing SBT +Install SBT for your appropriate operating system: +* [Windows Instructions](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html) + * Preferable method: install via .msi +* [Linux Instructions](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html) +* [MacOS Instructions](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Mac.html) + +#### Enabling Yarn from Within Node + +##### Do Not Use the Latest Version of Yarn +Do not upgrade versions of Yarn for repository. Do not follow the [instructions on Yarn’s official website](https://yarnpkg.com/getting-started/install). This will break the extension packaging process. +##### How to Enable +Type into the console `corepack enable yarn`. + +## Contributing and Setup + +### Forking the Project -## Contributing Due to this being an Apache project, if you would like to contribute, you will need to fork the daffodil-vscode main branch to your own repo of choice and create pull requests to the main branch with your code changes.  - -Once forked, you can clone that forked repository to your own local environment. This can be done by using `git clone`, followed by copy and pasting the https or ssh urls shown under the “Code” dropdown. -  + +### Cloning the Project to Local Environment +Once forked, you can clone that forked repository to your own local environment. This can be done by using `git clone`, followed by copy and pasting the https or SSH urls shown under the “Code” dropdown. We recommend using SSH. Instructions for setting up SSH can be found in [Setting up SSH Keys](#setting-up-ssh-keys). + +  -If you have not setup your ssh keys for github, you can follow this guide here: https://docs.github.com/en/authentication/connecting-to-github-with-ssh. Or you can use https or another method of your choice. +Once cloned, you can now create branches, commits, and push changes back to your remote fork. You may make changes with any IDE, but we highly encourage using VSCode for testing for maximum compatability. + +#### Setting up SSH Keys +Enter ssh-keygen into your terminal to generate an RSA key. Follow the prompts for naming the public and private key files (optional) and giving the keys an optional passphrase. + +The public and private keys are stored in a folder called .ssh in your users folder. The public key file is denoted with a .pub whereas the private key doesn’t have a file extension. + +Navigate to [SSH and GPG keys GitHub settings](https://github.com/settings/keys). Log into your GitHub account if needed. Click on New SSH Key. + + -Once cloned, you can now create branches, commits, and push changes back to your remote fork. You may make changes with any IDE, but because the extension is built for vscode, we recommend using that to maximize testing ability. +Give your new SSH Key a name and paste the contents of the .pub file into the key textbox + + +Note that the above image has parts of the key blurred out for confidentiality. + +Click on Add SSH key and follow GitHub prompts for verification. + +[GitHub has their own guide on setting up SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) which can be alternatively followed. + +### General Workflow Ensure that you keep your fork synced with the daffodil-vscode main by using the sync fork button, this ensures that you are developing with up to date code, so that you can be sure your changes work with present code.  - If any changes were made while you were working on yours, you will need to pull these changes down to your local environment and merge them with your changes before pushing back to remote. Once changes are pushed, you can make pull requests with completed changes back to the main daffodil-vscode branch. You can use the contribute drop down to create a pull request back to the main branch.  -## Building +### Opening the Repository in VSCode + +There are multiple ways of opening the repository that you have cloned in VSCode: + +1. In a terminal, type in `code <PATH TO THE CLONED REPOSITORY>` +2. Clicking on open folder at the VSCode homescreen + + + +3. At the top options bar, File -> Open Folder + + + +#### Recommended VSCode Extensions +Upon opening, VSCode may prompt you to install recommended extensions. Go ahead and accept installing the recommended extensions. +* [Prettier - Code formatter - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) + +#### Required VSCode Extensions +Daffodil-VSCode depends on the following extensions +* [JAR Viewer - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=wmanth.jar-viewer) +* [Highlight Matching Tag - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=vincaslt.highlight-matching-tag) + + +### Verifying Setup Can Build +Navigate inside your cloned folder in a terminal. Enter `yarn` to install required packages. If it prompts you to install yarn 1.22.XX, type `y`. + +Then type in `yarn package`. If there’s new .vsix file in the folder, then you have successfully set up your development environment correctly. For more information about `yarn package`, read [Yarn Package](#yarn-package). + + + +Lastly, run `yarn test`. All tests should pass without any errors. More information can be found under [Automated Testing Suite (Yarn Test)](#automated-testing-suite) + + + +Alternatively, you can run all of the commands in a single line by running `yarn && yarn package && yarn test && echo "All good!"`. + +#### Yarn Package If you would like to build to confirm that your changes compile, you can run the extension through the vscode debugger as shown below. Under the run and debugger, you should see a launch.json already loaded for the extension, just hit the green play button. This will open a new debug window of vscode that will have the extension built and running. You can then test any changes made and ensure it is operating as intended. Review Comment: Consider changing "If you would like to build to confirm that your changes compile" to "If you would like to confirm that your changes compile". Starting the the debug session starts "yarn run watch" in the terminal window. Also each time you open VS Code and start a debug session it will start "yarn run watch" in a terminal and build the extension. Also a message will popup.  We usually recommend the user wait until the build completes in the VS Code terminal window then click Debug Anyway. For any subsequent debug runs without closing VS Code the above message will not display. ########## DEVELOPMENT.md: ########## @@ -66,13 +243,238 @@ You can then take this .vsix file and install the extension into your vscode ins  +#### Automated Testing Suite + +The Apache Daffodil VS Code Extension comes with an automated test suite. Run it as follows: + +```shell +yarn test +``` + +##### Testing Against a Specific Version of VS Code + +By default, the test suite will use the earliest supported release of VS Code. To test against any _specific_ version of VS Code (in this example, VS Code version 1.74.3), execute the test suite as follows, setting `DAFFODIL_TEST_VSCODE_VERSION` to the desired version: + +```shell +DAFFODIL_TEST_VSCODE_VERSION=1.74.3 yarn test +``` + +Set `DAFFODIL_TEST_VSCODE_VERSION` to `stable` to use the latest stable release, or to `insiders` to use the latest (nightly) insiders build. + + +### Debugging the Extension + +Create a `sampleWorkspace` folder in the folder one level higher than where `daffodil-vscode` currently resides. For example, if you have your `daffodil-vscode` folder stored in a folder called repos, then make a folder in repos called `sampleWorkspace`. + + + +It’s advised to copy sample data files and sample DFDL schemas (.dfdl.xsd) in here. You can find DFDL schemas at [DFDL Schemas for Commercial and Scientific Data Formats](https://github.com/DFDLSchemas). + +Optional: If you would like to recompile the code when you're editing, run `yarn watch` before following the next steps. More information is outlined in [Automatically Recompile Code When it Changes](#automatically-recompile-code-when-it-changes) Review Comment: Pressing the button to start debugging automatically runs "yarn run watch" which will re-compile any changes as they are made. However for the changes to take affect you usually have to stop and restart debugging. ########## DEVELOPMENT.md: ########## @@ -66,13 +243,238 @@ You can then take this .vsix file and install the extension into your vscode ins  +#### Automated Testing Suite + +The Apache Daffodil VS Code Extension comes with an automated test suite. Run it as follows: + +```shell +yarn test +``` + +##### Testing Against a Specific Version of VS Code + +By default, the test suite will use the earliest supported release of VS Code. To test against any _specific_ version of VS Code (in this example, VS Code version 1.74.3), execute the test suite as follows, setting `DAFFODIL_TEST_VSCODE_VERSION` to the desired version: + +```shell +DAFFODIL_TEST_VSCODE_VERSION=1.74.3 yarn test +``` + +Set `DAFFODIL_TEST_VSCODE_VERSION` to `stable` to use the latest stable release, or to `insiders` to use the latest (nightly) insiders build. + + +### Debugging the Extension + +Create a `sampleWorkspace` folder in the folder one level higher than where `daffodil-vscode` currently resides. For example, if you have your `daffodil-vscode` folder stored in a folder called repos, then make a folder in repos called `sampleWorkspace`. + + + +It’s advised to copy sample data files and sample DFDL schemas (.dfdl.xsd) in here. You can find DFDL schemas at [DFDL Schemas for Commercial and Scientific Data Formats](https://github.com/DFDLSchemas). + +Optional: If you would like to recompile the code when you're editing, run `yarn watch` before following the next steps. More information is outlined in [Automatically Recompile Code When it Changes](#automatically-recompile-code-when-it-changes) + +Next start debugging the extension. Make sure the “Extension” debug configuration is currently selected. You can press the green run button or alternatively press F5. + + + +You may see this window pop up + + + +Click on debug anyway once yarn watch says webpack is fully compiled. + + + +A new VSCode window should’ve popped up with the sampleWorkspace opened. + + + +Open the command palette with `Ctrl + Shift + P` and type in `Daffodil Debug`. Select the `Configure launch.json` option. + + + +Your window should look like this. + + + +Scroll down and check these following options + + + +Click save + + + +Click on the Run and Debug Icon. Wizard Config should show at the top. + + + +Then select a schema file and a data file. (Note, if you want to hard code where the images are, you’re able to change the DFDL and data file path in the Daffodil Configure launch.json window) + + + + + +Your window should look like the following. Note that you may have to move some tabs around. + + + +Here’s an example view of the data editor (OmegaEdit) with the schema on the left. + + + +Here’s the infoset diff view. The infoset is the resulting output XML/JSON file. + + + +#### Changing the sampleWorkspace folder name and location +If you would like to specify a different name and/or location for the sampleWorkspace is, modify the following line in `.vscode/launch.json`: + + + +#### Test a Local Version of Apache Daffodil Debugge Review Comment: Debugger needs an 'r' at the end. ########## DEVELOPMENT.md: ########## @@ -66,13 +243,238 @@ You can then take this .vsix file and install the extension into your vscode ins  +#### Automated Testing Suite + +The Apache Daffodil VS Code Extension comes with an automated test suite. Run it as follows: + +```shell +yarn test +``` + +##### Testing Against a Specific Version of VS Code + +By default, the test suite will use the earliest supported release of VS Code. To test against any _specific_ version of VS Code (in this example, VS Code version 1.74.3), execute the test suite as follows, setting `DAFFODIL_TEST_VSCODE_VERSION` to the desired version: + +```shell +DAFFODIL_TEST_VSCODE_VERSION=1.74.3 yarn test +``` + +Set `DAFFODIL_TEST_VSCODE_VERSION` to `stable` to use the latest stable release, or to `insiders` to use the latest (nightly) insiders build. + + +### Debugging the Extension + +Create a `sampleWorkspace` folder in the folder one level higher than where `daffodil-vscode` currently resides. For example, if you have your `daffodil-vscode` folder stored in a folder called repos, then make a folder in repos called `sampleWorkspace`. + + + +It’s advised to copy sample data files and sample DFDL schemas (.dfdl.xsd) in here. You can find DFDL schemas at [DFDL Schemas for Commercial and Scientific Data Formats](https://github.com/DFDLSchemas). + +Optional: If you would like to recompile the code when you're editing, run `yarn watch` before following the next steps. More information is outlined in [Automatically Recompile Code When it Changes](#automatically-recompile-code-when-it-changes) + +Next start debugging the extension. Make sure the “Extension” debug configuration is currently selected. You can press the green run button or alternatively press F5. + + + +You may see this window pop up + + + +Click on debug anyway once yarn watch says webpack is fully compiled. + + + +A new VSCode window should’ve popped up with the sampleWorkspace opened. + + + +Open the command palette with `Ctrl + Shift + P` and type in `Daffodil Debug`. Select the `Configure launch.json` option. + + + +Your window should look like this. + + + +Scroll down and check these following options + + + +Click save + + + +Click on the Run and Debug Icon. Wizard Config should show at the top. + + + +Then select a schema file and a data file. (Note, if you want to hard code where the images are, you’re able to change the DFDL and data file path in the Daffodil Configure launch.json window) + + + + + +Your window should look like the following. Note that you may have to move some tabs around. + + + +Here’s an example view of the data editor (OmegaEdit) with the schema on the left. + + + +Here’s the infoset diff view. The infoset is the resulting output XML/JSON file. + + + +#### Changing the sampleWorkspace folder name and location +If you would like to specify a different name and/or location for the sampleWorkspace is, modify the following line in `.vscode/launch.json`: + + + +#### Test a Local Version of Apache Daffodil Debugge +The local Apache Daffodil™ Extension for Visual Studio Code downloads and caches the Apache Daffodil™ Debugger corresponding to the latest extension release. If you want to test a _local_ version of the Apache Daffodil Debugger, you need to: +* add `"useExistingServer": true` to the configuration in your `launch.json` in the sample workspace; +* launch the backend debugger locally, using a launch configuration like below: + ```json + { + "type": "scala", + "name": "DAPodil", + "request": "launch", + "mainClass": "org.apache.daffodil.debugger.dap.DAPodil", + "args": [] + } + ``` + This will start the debug adapter and await a connection from the Apache Daffodil VS Code Extension (usually on TCP port 4711); and +* debug your schema file, as long as it has the `useExistingServer` setting above. + +#### Automatically Recompile Code When it Changes + +To automatically recompile code when it changes, run `yarn watch`. Problems will show up in the `Problems` tab as `yarn watch` is active. You'll want to run `yarn watch` before you start debugging in Visual Studio Code. + +### Troubleshooting +You may run into issues with building, running tests, or debugging the extension. The follow sections will describe some issues you may encounter and discuss remedies. + +#### Yarn Package Issues +##### If Yarn Keeps Updating to The Latest Version +As of typing this document (Feb 2025), the latest version of yarn is 4.6.0. If you type `yarn` and your console outputs the following or anything similar: +``` +➤ YN0087: Migrated your project to the latest Yarn version �� +➤ YN0000: · Yarn 4.6.0 +➤ YN0000: ┌ Resolution step +➤ YN0085: │ + @omega-edit/client@npm:0.9.83, @tsconfig/svelte@npm:5.0.2, @types/glob@npm:8.1.0, @types/mocha@npm:10.0.6, @types/node@npm:20.11.30, @types/vscode-webview@npm:1.57.4, @types/vscode@npm:1.95.0, @viperproject/locate-java-home@npm:1.1.15, @vscode/debugadapter-testsupport@npm:1.65.0, @vscode/debugadapter@npm:1.67.0, @vscode/test-electron@npm:2.3.8, @vscode/vsce@npm:2.22.0, @vscode/webview-ui-toolkit@npm:1.4.0, await-notify@npm:1.0.1, chai@npm:4.4.1, and 703 more. +➤ YN0000: └ Completed in 9s 958ms +➤ YN0000: ┌ Post-resolution validation +➤ YN0002: │ apache-daffodil-vscode@workspace:. doesn't provide react (pa7c88), requested by @vscode/webview-ui-toolkit. +➤ YN0086: │ Some peer dependencies are incorrectly met by your project; run yarn explain peer-requirements <hash> for details, where <hash> is the six-letter p-prefixed code. +➤ YN0000: └ Completed +➤ YN0000: ┌ Fetch step +➤ YN0013: │ 696 packages were added to the project (+ 397.25 MiB). +➤ YN0000: └ Completed in 4m 47s +➤ YN0000: ┌ Link step +➤ YN0007: │ esbuild@npm:0.19.9 must be built because it never has been before or the last one failed +➤ YN0007: │ svelte-preprocess@npm:5.1.1 [5fe27] must be built because it never has been before or the last one failed +➤ YN0007: │ svelte-preprocess@npm:5.1.1 [ab741] must be built because it never has been before or the last one failed +➤ YN0007: │ keytar@npm:7.9.0 must be built because it never has been before or the last one failed +➤ YN0007: │ protobufjs@npm:7.4.0 must be built because it never has been before or the last one failed +➤ YN0000: └ Completed in 2m 40s +➤ YN0000: · Done with warnings in 7m 37s +``` +this means that there is a yarn project that is initialized in a folder that’s higher up from the cloned repository folder. This will negatively affect the extension packaging process. A remedy for the issue is to remove all yarn files and the package.json file in the higher folder that the yarn project is initialized in. + +To remedy this, you need to change versions of Yarn. Use `yarn set version 1.22.22` to change versions of Yarn. [Documentation for set-version](https://yarnpkg.com/cli/set/version). + +#### Yarn Test Issues +##### Data Editor Opens Test Case Failing + +This means port 9000 is Occupied. See the current workarounds section in ["data editor opens" test fails if Port 9000 is Occupied · Issue #1175 · apache/daffodil-vscode](https://github.com/apache/daffodil-vscode/issues/1175). + +##### TLS Certificate Issues + +HTTPS TLS certificates are verified by default. When running the test suite in certain environments (e.g., company VPN that uses endpoint protection), TLS certificate verifications may fail with a self-signed certificate error. If this is the case, either have node trust the endpoint protection certificate, or use one of these workarounds to disable the certificate verification: + +```shell +NODE_TLS_REJECT_UNAUTHORIZED=0 yarn test +``` + +or + +```shell +node ./out/tests/runTest.js --disable_cert_verification +``` + +**WARNING:** Do not `export NODE_TLS_REJECT_UNAUTHORIZED=0` into your environment as it will disable TLS certificate verification on _all_ node HTTPS connections done in that shell session. + +#### Debugging Issues +##### SELinux Port Functionality +If you’re running into frequent issues with connectivity or VSCode freezing, it may be worth it to disable SELInux enforcing mode. +To check to see if SELinux OS is in enforcing mode, you can type `getenforce` in a console. If it outputs Enforcing, you’ll want to set it to Permissive by using `sudo setenforce Permissive`. + +##### Windows Yarn Test Window Not Loading Extensions +If you run `yarn test`, and are running into an issue where the test window is saying there’s a missing dependent extension + + + +and yarn tests under the `getCommands` section are failing, + + + +Inside of src\tests\runTest.ts, replace +``` + { + encoding: 'utf-8', + stdio: 'inherit', + } +``` +with +``` + { + encoding: 'utf-8', + stdio: 'inherit', + shell: os.platform().toLowerCase().startsWith('win'), + } +``` +and add +`import os from 'os'` +near the top of the file along with the other import statements. + +#### Re-trying Verification After Errors +Type in `git clean -fdx`. Then run `yarn && yarn package && yarn test && echo "All good!"`. +If issues persist, you may want to uninstall Node and reinstall it. If that doesn’t remedy the issue, you may have to create a fresh VM. + +## Building the Documentation + +### Install Pandoc + +Before running commands to build the documentation, be sure to [install Pandoc](https://pandoc.org/installing.html). + +### Command to build the Documentation + +To build `docx` (Word formatted) documentation, from the top of the cloned repository, run: + +```shell +cd docs && make all +``` + +## Reviewing and Verifying Dependency Bot Updates + +For GitHub CI action updates (pull requests that start with **Bump actions/...**), make sure the affected workflows still operate as expected (they are automatically CI tested). GitHub CI actions update workflow YAML files, and are part of the CI infrastructure and not a code dependency. These should be relatively quick and easy to assess compared to code dependencies. + +If the updates are not GitHub CI action updates, then additional scrutiny is required. When reviewing and verifying dependency bot updates that are part the software supply chain being distributed, please use the following checklist: + +- [ ] **Do all automated continuous integration checks pass?** +- [ ] **Is the update a patch, minor, or major update?** +- [ ] **Is the license still compatible with ASF License Policy?** +- [ ] **Have any changes been made to LICENSE/NOTICE files that need to be incorporated?** +- [ ] **Have any transitive dependencies been added or changed?** + +## Testing Information +Testing for this extension comprsies of unit testing, CI/CD tests for pull requests (PRs), and manual tests. Review Comment: Correct "comprises" spelling. ########## DEVELOPMENT.md: ########## @@ -15,38 +15,215 @@ limitations under the License. --> -# Welcome -If you would like the latest stable release of the extension, please reference the README.md for instructions on how to retrieve that. -You can download a zip archive of the source code for the extension. You can extract this to any directory of your choice and open it within vscode to begin poking around. +# Daffodil-VSCode Developer's Guide -The project currently has many components and is growing, please refer to the wiki for an overview of what the extension includes. There is also user documentation on the right side with additional release specific use case guides. Here is the one for v1.3.1: -https://github.com/apache/daffodil-vscode/wiki/Apache-Daffodil%E2%84%A2-Extension-for-Visual-Studio-Code:-v1.3.1 +## Build Status + +[](https://github.com/apache/daffodil-vscode/actions/workflows/CI.yml) +[](https://github.com/apache/daffodil-vscode/actions/workflows/nightly.yml) + +## Table of Contents + +- [Daffodil-VSCode Developer's Guide](#daffodil-vscode-developers-guide) + * [Build Status](#build-status) + * [Table of Contents](#table-of-contents) + * [Welcome](#welcome) + * [Prerequisites ](#prerequisites) + + [Install Git](#install-git) + + [Install Visual Studio Code (VSCode)](#install-visual-studio-code-vscode) + * [Installing Build Requirements](#installing-build-requirements) + + [Summary of Build Requirements](#summary-of-build-requirements) + + [Step-by-step Guide for Installing Build Requirements](#step-by-step-guide-for-installing-build-requirements) + - [Installing Node](#installing-node) + * [Installing Node on Windows Note ](#installing-node-on-windows-note) + - [Installing Java (JDK 17)](#installing-java-jdk-17) + * [Build Issues with Higher JDK Versions ](#build-issues-with-higher-jdk-versions) + * [Switching Java Versions on Linux](#switching-java-versions-on-linux) + - [Installing SBT](#installing-sbt) + - [Enabling Yarn from Within Node](#enabling-yarn-from-within-node) + * [Do Not Use the Latest Version of Yarn](#do-not-use-the-latest-version-of-yarn) + * [How to Enable](#how-to-enable) + * [Contributing and Setup](#contributing-and-setup) + + [Forking the Project](#forking-the-project) + + [Cloning the Project to Local Environment](#cloning-the-project-to-local-environment) + - [Setting up SSH Keys](#setting-up-ssh-keys) + + [General Workflow](#general-workflow) + + [Opening the Repository in VSCode](#opening-the-repository-in-vscode) + - [Recommended VSCode Extensions](#recommended-vscode-extensions) + - [Required VSCode Extensions](#required-vscode-extensions) + + [Verifying Setup Can Build](#verifying-setup-can-build) + - [Yarn Package](#yarn-package) + - [Automated Testing Suite](#automated-testing-suite) + * [Testing Against a Specific Version of VS Code](#testing-against-a-specific-version-of-vs-code) + + [Debugging the Extension](#debugging-the-extension) + - [Changing the sampleWorkspace folder name and location](#changing-the-sampleworkspace-folder-name-and-location) + - [Test a Local Version of Apache Daffodil Debugge](#test-a-local-version-of-apache-daffodil-debugge) + - [Automatically Recompile Code When it Changes](#automatically-recompile-code-when-it-changes) + + [Troubleshooting](#troubleshooting) + - [Yarn Package Issues](#yarn-package-issues) + * [If Yarn Keeps Updating to The Latest Version](#if-yarn-keeps-updating-to-the-latest-version) + - [Yarn Test Issues](#yarn-test-issues) + * [Data Editor Opens Test Case Failing](#data-editor-opens-test-case-failing) + * [TLS Certificate Issues](#tls-certificate-issues) + - [Debugging Issues](#debugging-issues) + * [SELinux Port Functionality](#selinux-port-functionality) + * [Windows Yarn Test Window Not Loading Extensions](#windows-yarn-test-window-not-loading-extensions) + - [Re-trying Verification After Errors](#re-trying-verification-after-errors) + * [Building the Documentation](#building-the-documentation) + + [Install Pandoc](#install-pandoc) + + [Command to build the Documentation](#command-to-build-the-documentation) + * [Reviewing and Verifying Dependency Bot Updates](#reviewing-and-verifying-dependency-bot-updates) + * [Testing Information](#testing-information) + * [Monitoring Project Status](#monitoring-project-status) + * [Thank you for your interest in contributing to this project!](#thank-you-for-your-interest-in-contributing-to-this-project) + +## Welcome + +This guide contains developer-oriented instructions on how to setup your local development environment for contributing to this project. + +If you would like the latest stable release of the extension, please reference the [README file](README.md). + +The project is currently growing, please refer to the [wiki](https://github.com/apache/daffodil-vscode/wiki) for an overview of what the extension includes. There is also user documentation on the right pane with release specific use case guides. + +## Prerequisites + +### Install Git +If your system doesn’t have Git installed, [install Git](https://git-scm.com/downloads). Select the appropriate operating system and follow the listed instructions. +To verify git is installed on your system, enter git -v into your system’s terminal and it should display the version of git if properly installed. + +### Install Visual Studio Code (VSCode) + +Install VSCode per [official VSCode documentation](https://code.visualstudio.com/docs/setup/setup-overview): +* [Windows](https://code.visualstudio.com/docs/setup/windows) +* [Linux](https://code.visualstudio.com/docs/setup/linux) +* [MacOS](https://code.visualstudio.com/docs/setup/mac) + +## Installing Build Requirements +This section will provide describe what requirements are needed to build with a step-by-step guide to assist developers of varying skill levels. The steps provide recommended methods for installing build requirements, but don't have to be followed exactly one-to-one. + +### Summary of Build Requirements + +- Java Development Kit (JDK) 17 or lower, but higher than or equal to 8 +- SBT 0.13.8 or higher +- Node 16 or higher +- [Yarn Classic](https://classic.yarnpkg.com/en/docs/install#windows-stable) + +### Step-by-step Guide for Installing Build Requirements + +#### Installing Node +Navigate to the [Node Download page](https://nodejs.org/en/download). Select the instructions for installing the latest LTS version of Node.js for your operating system using fnm with npm. + + +##### Installing Node on Windows Note +Make sure you have `winget` installed. If it’s not installed, you can install it by typing in `Install-Module -Name Microsoft.WinGet.Client` into PowerShell. +After following all the steps outlined on Node’s page, you want to [create a PowerShell profile](https://lazyadmin.nl/powershell/powershell-profile/) which is a PowerShell script that gets executed every time a new instance of PowerShell is opened. Then append `fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression` per [fnm's guidance](https://github.com/Schniz/fnm?tab=readme-ov-file#powershell). + +#### Installing Java (JDK 17) +You can install [Oracle's JDK 17](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) or alternatively install the OpenJDK equivalent. + +##### Build Issues with Higher JDK Versions +Note that higher versions of the JDK may cause extension building issues and is not advised. + +##### Switching Java Versions on Linux +You might have Java already installed. You can change the default Java provider and version by running `sudo update-alternatives --config java`. + +#### Installing SBT +Install SBT for your appropriate operating system: +* [Windows Instructions](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html) + * Preferable method: install via .msi +* [Linux Instructions](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html) +* [MacOS Instructions](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Mac.html) + +#### Enabling Yarn from Within Node + +##### Do Not Use the Latest Version of Yarn +Do not upgrade versions of Yarn for repository. Do not follow the [instructions on Yarn’s official website](https://yarnpkg.com/getting-started/install). This will break the extension packaging process. +##### How to Enable +Type into the console `corepack enable yarn`. + +## Contributing and Setup + +### Forking the Project -## Contributing Due to this being an Apache project, if you would like to contribute, you will need to fork the daffodil-vscode main branch to your own repo of choice and create pull requests to the main branch with your code changes. Review Comment: Consider changing "Due to this being an Apache project," to "This is an Apache project,". Also consider providing a link to https://gitub.com/apache/daffodil-vscode. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
