Skip to content

Latest commit

 

History

History
266 lines (197 loc) · 11.2 KB

CONTRIBUTING.md

File metadata and controls

266 lines (197 loc) · 11.2 KB
Raw

How to contribute

Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved!

For Getting Started instructions, see:

For issue reporting, use Github Issues and follow the procedures documented here:

Personal support request (or getting contribution help) should be discussed on F# Software Foundation Slack or the F# Discord.

Getting Started

First things first! In order to build & develop Ionide locally, you'll need to install the following.

Prerequisites

First-Time Build

  1. Fork the Ionide repo https://github.com/ionide/ionide-vscode-fsharp on github.

  2. Clone your fork:

    git clone [email protected]:YOUR_GITHUB_USER/ionide-vscode-fsharp.git

    or if you don't use ssh:

    git clone https://github.com/YOUR_GITHUB_USER/ionide-vscode-fsharp.git

  3. Open the repo in your terminal:

    cd ionide-vscode-fsharp

  4. Then build the project by running the build script: (on Mac/Linux)

    ./build.sh

    (or on Windows)

    .\build.cmd

  5. Voilà! You're ready to run Ionide.

Skip to the Launching Ionide section if the build succeeded.

Otherwise, check out the Troubleshooting Build Failures guide.

Running a Full Build

This should always be done at least once after any clone/pull.

./build.sh -t Build

(or on Windows)

.\build.cmd -t Build

This will re-install any necesssary packages and files.

Troubleshooting Build Failures

  • If the FsAutoComplete dependency fails to build, you can re-run it manually:

      # browse to the FsAutoComplete source code folder
  cd paket-files/github.com/fsharp/FsAutoComplete
  # build FsAutoComplete (Mac/Linux)
  ./build.sh LocalRelease
  # build FsAutoComplete (Windows)
  .\build.cmd LocalRelease

  • If dotnet restore gives the error The tools version "14.0" is unrecognized, then you need to install [msbuildtools2015][msbuildtools2015]

  • If dotnet restore gives the error error MSB4126: The specified solution configuration "Debug|x64" is invalid, there's a good chance you have the Platform environment variable set to "x64". Unset the variable and try the restore command again.

  • If ./build.sh gives errors, you may need to run ./build.sh -t Build one time.

Launching Ionide

When you're ready to test out some code changes, you can use vscode's Run View to build and launch Ionide in a new Extension Development Host instance, which is a separate "dev mode" instance of VS code used for developing extensions.

First, open the Ionide project folder in vscode.

cd ionide-vscode-fsharp # or whereever you cloned the ionide repo.
code .

Then, you can open Ionide in a new Extension Development Host using one of the following methods:

Build and Launch Extension

This builds the extension and launches it immediately in a new vscode extension host.

  1. Open the "Run and Debug" menu (cmd+shift+d or ctrl+shift+d).
  2. Choose the Build and Launch Extension launch configuration
  3. Run it by pressing F5.

Watch Mode (Recommended)

There are two steps involved in running Ionide in Watch Mode.

TL;DR: watch this video clip:

ionide_watch.mp4
  1. Start the Watch task.
    • Open the command palette (cmd+shift+p or ctrl+shift+p)
    • Enter tasks: run tasks.
    • Enter watch.
    • Wait a few seconds. It might take 15-30 seconds for the initial build to complete
  2. Run the Launch Only launch configuration.
    • Open the Run and Debug menu (cmd+shift+d or ctrl+shift+d)
    • Choose the Launch Only configuration
    • Run it by pressing F5.

Note: Step 1 starts a new "Watch" task that rebuilds Ionide in the background while you're making source code changes. You should wait for this to finish before opening the Extension Host.

If you're curious what's going on, you can view the log output for this task by running Tasks: Show Running Tasks from the command palette.

Working with FSAC (FSharpAutoComplete)

Most Ionide bugs are actually from there. This repo only stores the glue code between FSAC and Visual Studio Code - not the actual implementation of behaviours you would experience when using Ionide in Visual Studio Code which are implemented in FSAC.

  1. Fork the FSAC repo https://github.com/fsharp/FsAutoComplete on github.

  2. Clone your fork:

    git clone [email protected]:YOUR_GITHUB_USER/FsAutoComplete.git

    or if you don't use ssh:

    git clone https://github.com/YOUR_GITHUB_USER/FsAutoComplete.git

  3. Follow the FSAC build instructions and copy the dll output from the output log, it should be a path inside the FSAC repo ending with src/FsAutoComplete/bin/Release/net6.0/fsautocomplete.dll. (Alternatively, delete the net6.0/fsautocomplete.dll part and it will also work.) Note that Release may be substituted with Debug if you build with that configuration instead. Also, note that net6.0 may be replaced with another .NET version like net7.0 as FsAutoComplete targets a newer .NET version.

  4. In the instance of VSCode that you have Ionide open, open settings (CMD , or Ctrl , by default), and find the section FSharp > Fsac: Net Core Dll Path and paste the output you copied from step 3.

  5. Now find the section FSharp > Fsac: Attach Debugger and check the check box.

  6. Close settings

  7. Goto the debug section and hit Build and Launch extension, after a while another instance of VSCode will start, you can use this instance to test Ionide/FsAutoComplete.

  8. To attach the debugger go back to the instance of VSCode where you open FSAC and goto the debug section, hit .NET Core Attach in the list shown you should see all the dotnet processes running, choose one that has fsautocomplete.dll --mode lsp --attachdebugger shown.

  9. Now you will be able to use breakpoints in the FsAutocomplete solution to debug the instance from step 6.

There is a video here that goes through the steps and fixing a bug in a little more detail.

Remove the settings from steps 3 and 4 to go back to FSAC bundled in Ionide extension.

FSAC Dependencies

Pull requests

Good pull requests - patches, improvements, new features - are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.

IMPORTANT: By submitting a patch, you agree that your work will be licensed under the license used by the project.

If you have any large pull request in mind (e.g. implementing features, refactoring code, etc), please ask first otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.

Please adhere to the coding conventions in the project (indentation, accurate comments, etc.).

Bug reports

A bug is either a demonstrable problem that is caused in Ionide failing to provide the expected feature or indicate missing, unclear, or misleading documentation. Good bug reports are extremely helpful - thank you!

Guidelines for bug reports:

  1. Use the GitHub issue search — check if the issue has already been reported.

  2. Check if the issue has been fixed — try to reproduce it using the master branch in the repository.

  3. Isolate and report the problem — ideally create a reduced test case.

Please try to be as detailed as possible in your report. Include information about your Operating System, as well as your dotnet (or mono \ .NET Framework), and F# versions. Please provide steps to reproduce the issue as well as the outcome you were expecting! All these details will help developers to fix any potential bugs.

Ionide provide an easy way to gather all this information:

Do Ctrl+Shift+P > F#: Get info for diagnostics, this will open a file with something like:

Problem

Steps to reproduce

Machine infos

  • Operating system: Darwin
  • Arch: x64
  • VSCode: 1.23.1
  • Runtime: netcore
  • Dotnet version: 2.1.103

Now, you can copy/paste this file in the issue on github and fill the gaps. You can let the lines started by <!-- they will not be displayed by github.

Feature requests

Feature requests are welcome and should be discussed on issue tracker. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the community of the merits of this feature. Please provide as much detail and context as possible.

Release

  1. Dependencies
    1. If updating FSAC
      1. run dotnet paket update --group fsac
      2. Commit the paket.lock
    2. If updating ionide-grammar
      1. open paket.lock
      2. find the line remote: https://github.com/ionide/ionide-fsgrammar.git
      3. update the hash to the latest commit on the main branch
      4. Commit the paket.lock
    3. if updating ionide-vscode-helpers
      1. open paket.dependencies
      2. find the lines for github ionide/ionide-vscode-helpers
      3. Update the hash for all the files
      4. run dotnet paket install
      5. Commit the paket.dependencies and paket.lock
  2. Add version and notes to RELEASE_NOTES.md
    1. If possible link the pull request of the changes and mention the author of the pull request
    2. If updating FSAC mention the version of FSAC that is being updated to and link it's release notes
  3. Commit RELEASE_NOTES.md
    1. git commit -m "Bump version to x.x.x"
    2. git push [remote-branch] main
  4. Goto the Release workflow on Github Action
    1. Click Run workflow in the upper right
    2. Click Run workflow button on the dialog that pops up