CONTRIBUTING.md

Contributing

WebSharper is a Free Software project, and we welcome your contributions!

The UI repository contains the WebSharper.UI reactive programming and HTML libraries. WebSharper consists of this repository as well as a constellation of libraries and extensions, located in the dotnet-websharper GitHub organization. Don't hesitate to contribute to these too!

• What to contribute
• How to contribute
  • Required software
  • Building from the command line
  • Setting up your development environment
  • Running the tests
  • Project structure

What to contribute?

We welcome all types of contributions, particularly:

• Bug fixes in the issue tracker
• Library improvements
• Feature suggestions are welcome on the Gitter chat and the issue tracker; we suggest that you discuss new features with the rest of the team on these channels before getting started on implementation.

How to contribute

Required software

It is possible to work on WebSharper on Windows, Linux and OSX.

To compile this project, you need the following installed:

• The .NET Core SDK 2.1.300 or newer. You can download it here.
• The .NET Framework 4.6.1.
  • For Windows, it is preinstalled, or you can download it here.
  • For Linux and OSX, this is provided by Mono. You can follow the install instructions here. For Linux, you should also follow the instructions to install xsp in order to run the test project.

Building from the command line

This project can be built using the script build.cmd on Windows, or build.sh on Linux andr OSX. In the following shell snippets, a command line starting with build means .\build.cmd on Windows and ./build.sh on Linux and OSX.

Simply running build compiles the UI libraries and tests in debug mode. The following targets are available:

• build ws-builddebug

  Equivalent to simple build: compiles the libraries and tests in debug mode.

• build ws-buildrelease

  Compiles the libraries and tests in release mode.

• build ws-package

  Compiles the libraries and tests in release mode, then creates NuGet packages in the build folder.

• build ws-clean

  Deletes temporary and output directories.

The following options are available:

• build [TARGET] -ef verbose

  Makes compilation more verbose. Equivalently, set the verbose environment variable to true.

Setting up your development environment

We recommend that you use one of the following development environments:

• On Windows: Visual Studio 2017.
• On all platforms: Visual Studio Code with the following extensions:
  • ionide-fsharp for F# support
  • ms-vscode.csharp for C# support

Running the tests

WebSharper defines and uses its own test framework, WebSharper.Testing. It runs on the client side and is backed by qUnit. So running the WebSharper test suite consists in running a web application which looks like this:

This repository contains several test projects, detailed in the project structure. They are ASP.NET applications hosting WebSharper applications; some of them are Client-Server applications, others are SPAs. Here is how to run them:

• If you are using Visual Studio, you can simply open WebSharper.sln, set the test project you want as the startup project, and Run.

• On Linux or OSX, you can browse into the project's folder and simply run xsp.

Project structure

Here is the detail of the project structure:

• Libraries:
  • WebSharper.UI contains the core library for both reactive programming and DOM management.
  • WebSharper.UI.CSharp contains the C#-friendly API for WebSharper.UI.
  • WebSharper.UI.Templating.Common contains the code for HTML templating that is needed both during compilation and during server-side runtime.
  • WebSharper.UI.Templating.Runtime contains the server-side and client-side runtime for the HTML templating.
  • WebSharper.UI.Templating contains the F# type provider for HTML templating.
  • WebSharper.UI.CSharp.Templating contains the C# code generator for HTML templating.
  • WebSharper.UI.CSharp.Templating.Analyzer contains the Roslyn analyzer that invokes the code generator on file save in Visual Studio.
  • WebSharper.UI.CSharp.Templating.Build contains the MSBuild task that invokes the code generator pre-compilation.
• Tests:
  • WebSharper.UI.Tests contains all the F# tests that do not rely on HTML templating.
  • WebSharper.UI.Templating.Tests contains the F# client-side HTML templating tests.
  • WebSharper.UI.Templating.ServerSide.Tests contains the F# server-side HTML templating tests.
  • WebSharper.UI.Routing.Tests contains the F# router tests.
  • WebSharper.UI.CSharp.Tests contains all the C# tests.