FAKE - F# Make - A DSL for build tasks and more FAKE
6.0.0
Edit this page

Lookig for older versions of the documentation, pre FAKE v6? See 

v5.fake.build

Contributing to FAKE

Table of Content:

Thank you for your interest in contributing to FAKE! This guide explains everything you'll need to know to get started.

Before diving in, please note:

Prerequisites

Before building and developing FAKE, you must:

Install F#

Linux and Mac users should install the .NET Core SDK and Mono per this guide, "Cross-Platform Development with F#".

Windows users can install Visual Studio. The Community Edition is freely available for open-source projects.

When developing on Windows, make sure to have long paths enabled (instructions available here), otherwise the test-suite will fail -- although, the build should work.

Install an Editor

For FAKE development, Visual Studio Code with Ionide is highly recommended. The following IDEs are also excellent choices:

Install FAKE

You can quickly install and use FAKE with the dotnet SDK (we use fake-cli as local tool):

cd /projects/FAKE
dotnet tool restore
dotnet fake --version

For alternative methods of installing FAKE, please see the Getting Started guide.

Creating Pull Requests

  1. Fork the FAKE repo on GitHub.

  2. Clone your personal fork locally.

  3. Add a new git remote in order to retrieve upstream changes.

    git remote add upstream https://github.com/fsprojects/FAKE.git

  4. Checkout the master branch.

    git checkout master

  5. To verify that everything works, build master via:

    dotnet fake build

  6. Create a new feature branch.

    git checkout -b myfeature

  7. Implement your bugfix/feature.

  8. Add a bit of documentation (see the section on Contributing Documentation).

  9. Re-run the build script to confirm that all tests pass.

    dotnet fake build

  10. Commit your changes, and push them to your fork.

  11. Use GitHub's UI to create a pull request. (Write "WIP" into the pull request description if it's not completely ready.)

    If you need to rebase you can do:

    git fetch upstream
git rebase upstream/master
git push origin myfeature -f

The pull request will be updated automatically.

Contributing Documentation

The code for all documentation can be found in the docs directory on GitHub. If you find a bug or add a new feature, make sure you document it!

The documentation uses the following stack:

TailwindCSS can be considered a pre step in build process, after that it will be handled to FSDocs. FSDocs is an amazing F# Docs library that turns Markdown files *.md with embedded code snippets and F# script *.fsx files containing embedded Markdown documentation into nice HTML documentation.

The docs directory is first built using NPM by running the command npm run build to generate styles and other files. Next fsdocs is called to generate the complete site and API documentation. FSDocs uses template pages to generate the site. We have two template pages:

The two templates are 90% identical, except some styles for markdown files to use TailwindCSS typography plugin.

The next part is the docs/data.json file. This file has the navigation and content of the site. The side navigation for guide and API Docs is built using this file. So to add new articles or modules to FAKE, this file need to be updated to include the new module/article.

Another part is the following. If you want to modify the styles, you can run TailwindCSS dev server by navigating to docs directory and entering the following command in a CMD:

npm run dev

Building the Documentation

To build the documentation from scratch, simply run:

dotnet fake build target GenerateDocs

To save time, you may skip the prerequisite build steps and run the GenerateDocs target directly using the single target -s switch:

dotnet fake build -s target GenerateDocs

(Note: this assumes binaries are already built and have not been modified.)

Viewing the Documentation

Running the following target spins up a webserver on localhost and opens the newly built docs in a browser window:

dotnet fake build target HostDocs

Testing Modules

If you make a change to a module and would like to test it in a fake script, the easiest way to do this is to create a local nuget package and reference it in your script per the steps below:

  1. Create a local nuget package for the module you've changed.
    e.g: Using dotnet cli 
cd path/to/project
    dotnet pack
  1. dotnet pack will create a default nuget package with version of 1.0.0 in the bin/Debug of your project. Set an additional paket source in your build script to this directory, and require this exact version in your paket references.

e.g: If you wanted to test a local build of Fake.DotNet.NuGet

#r "paket:
        source path/to/Fake.DotNet.NuGet/bin/Debug/
        source https://api.nuget.org/v3/index.json
        ...Other Dependencies...
        nuget Fake.DotNet.NuGet == 1.0.0 //" //Require version 1.0.0, which is the local build

Style Guidelines

From FAKE v6, FAKE uses Fantomas as a code formatter and style guideline tool. The tool will be run automatically on codebase to check if any style guidelines are not being followed. To accomplish that, the target CheckFormatting in build.fsx script will be run on each build of the codebase to ensure all files follow guideline. If not, then build will fail with instructions on what should be done to follow the guideline.

A useful way to ensure you are not waiting for build to fail when run it, is to add a GIT hook on pre-commit to run Fantomas. Please see Fantomas GIT hook documentation page. For FAKE usage, you need to run the following command:

dotnet fantomas  src/app/ src/template/ src/test/ --recurse

For development setup, we advise the following:

API Design Guidelines

We've learned from our mistakes and adopted new API design guidelines. Please read them very carefully, and please ask if you don't understand any of the following rules:

Considerations Regarding FAKE 4

Porting Legacy Modules to Current Version of FAKE

As mentioned in the Fake 5 and above learn more section, we could use your help porting modules to FAKE 5. To save you from some pitfalls, this section provides a working approach to migrating modules.

Try the following:

These steps will ensure:

Release Process

To publish a release, merge the changes to master branch and prepare release notes in RELEASE_NOTES.md file, and trigger the release GitHub action providing as an input the release version. The release process needs an admin approval, once that is approved the release action will start. FAKE release push packages to the following registries:

  1. Pushing all FAKE modules to NuGet source.
  2. Pushing FAKE as a chocolatey package.
  3. Publish site to GitHub Pages.

Staging environment

In order to test and preview our changes faster, we have a fully automated release process in place. This staging environment is based on VSTS and MyGet.

If you ever need a release/bugfix, make sure to mention that in your PR. We can quickly provide a build on the following infrastructure:

Because of package retention policies those builds will not be available forever! We will quickly release the builds once everything works. Those bits should be considered for "unblocking"-purposes or testing only.

The release process is publicly available as well.

Notes for Maintainers

FAKE uses GitHub actions in build process. We have two GitHub actions; the build_and_test and release actions. The build_and_test action is the action triggered on PRs and pushes to master branch. To validate changes in a PR.

The release action is responsible on release a new release of FAKE. It is triggered manually and needs an admin approval be it kick-off the release process. The release action uses API Keys to interact with services that packages will be pushed to. These keys are hosted in production environment in GitHub repository.