Table of Content:
- Creating Pull Requests
- Contributing Documentation
- Testing Modules
- Style Guidelines
- Considerations Regarding FAKE 4
- Porting Legacy Modules to Current Version of FAKE
- Release Process
- Staging environment
- Notes for Maintainers
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:
You are encouraged to improve this document by sending a pull request to the FAKE project on GitHub. If you learn
If you'd like to discuss a feature (a good idea!) or are looking for suggestions on how to to contribute:
- Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the Project shall
Before building and developing FAKE, you must:
You can quickly install and use FAKE with the dotnet SDK (we use fake-cli as local tool):
Clone your personal fork locally.
Add a new git remote in order to retrieve upstream changes.
git remote add upstream https://github.com/fsprojects/FAKE.git
git checkout master
To verify that everything works, build
dotnet fake build
Create a new feature branch.
git checkout -b myfeature
Implement your bugfix/feature.
Re-run the build script to confirm that all tests pass.
dotnet fake build
Commit your changes, and push them to your fork.
git fetch upstream git rebase upstream/master git push origin myfeature -f
The pull request will be updated automatically.
The documentation uses the following stack:
- as a styling framework
- as a JS framework for adding interactivity to website
- to generate API documentation from FAKE modules
TailwindCSS can be considered a pre step in build process, after that it will be handled to FSDocs. FSDocs is an
that turns Markdown files
*.md with embedded code snippets and F# script
*.fsx files containing embedded
Markdown documentation into nice HTML documentation.
docs directory is first built using NPM by running the command
npm run build to generate styles and other files.
fsdocs is called to generate the complete site and API documentation. FSDocs uses template pages to generate the site.
We have two template pages:
docs/_template.html: used for markdown files in
docs/reference/_template.html: used in API documentation
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
docs directory and entering the following command in a CMD:
To build the documentation from scratch, simply run:
To save time, you may skip the prerequisite build steps and run the
GenerateDocs target directly using the single target
(Note: this assumes binaries are already built and have not been modified.)
Running the following target spins up a webserver on localhost and opens the newly built docs in a browser window:
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:
Create a local nuget package for the module you've changed.
e.g: Using dotnet cli
dotnet packwill create a default nuget package with version of 1.0.0 in the
bin/Debugof 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
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
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:
For development setup, we advise the following:
- When working on FAKE 5 or above, with helps a lot!
- Read the .
- Read the below.
- Add documentation for your feature
- If you add new markdown documentation, make sure to link to it from an existing site. Ideally, add it to the
- If you write API documentation but no extra markdown, please consider adding it to the menu as well.
[<AutoOpen>]is no longer used
- Use Verbs as much as possible for functions
- In order to have a more consistent API, we propose to always use camelCase naming for functions
- For historic reasons, we allow constants and values in PascalCase. (They will not have a "verb" as they don't do anything)
If we provide optional parameters (via
static member), we use PascalCase as well (Example:
We assume the caller is not opening the module but only the global namespaces
Fake.IO, ... and make sure the code looks nice and structured on the caller side.
For compatibility reasons (migration from legacy), we assume the user doesn't open the global
-> This means we don't add anything in there in the new API.
Old APIs are marked as Obsolete with a link (hint) to the new API location. We use codes to make explicit
- FAKE0001 for moving part from one Module to another
- FAKE0002 for removed API we don't know who is using it and how => please open an issue if you use it
- FAKE0003 for API that is no more accessible (basically became internal) => please open an issue if you use it
- FAKE0004 for API not yet migrated, waiting for your contribution
Operators are opened seperatly with a separate
We avoid the
Helperssuffix (because we now expect users to write
We generally use the
[<RequireQualifiedAccess>]attribute on modules.
- Fake 4 (FakeLib) is in maintenance mode. Therefore new features need to be at least available as a new FAKE 5 and above module
- (that might mean that the old module needs to be migrated as part of the PR).
Fake 4 still allows hotfixes. Please send the PR against the hotfix_fake4 branch.
It would be helpful if a second PR against
masteris sent that merges the hotfix into
- and adds the hotfix to the FAKE 5 and above code as well.
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:
- Copy one of the existing netcore projects and edit the project file by hand (rename)
- Copy the old implementation files from
/src/app/Fake.<ModuleType>.<Name>(update project file again if required)
- (Optionally, there is no need for new stuff to appear in FakeLib at this point) Reference the new files in FakeLib (again updating
FakeLib.fsprojby hand to properly reference the stuff)
Fake.sln, add the project and go from there.
- Once stuff compiles in the (
Fake.sln) solution you are usually good to go. Let us know if you struggle at this point (in the PR or a new issue).
- Add the info about the new module to the
build.fsx. From this point on the build script will let you know if anything is missing. Again, if you have problems let us know.
- Mark the old module with the
- Test everything with a full
dotnet fake build
These steps will ensure:
- People using the NuGet package will get the warnings to update the new API
- The new API is part of FakeLib (deprecated)
- The new API is available as separate module
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
- Pushing all FAKE modules to NuGet source.
- Pushing FAKE as a chocolatey package.
- Publish site to GitHub Pages.
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:
- Website: https://staging.fake.build
- Chocolatey package:
choco install fake --version <version> --source https://www.myget.org/F/fake-chocolatey-vsts/api/v2
- NuGet feed: https://www.myget.org/F/fake-vsts/api/v3/index.json
- GitHub Releases: https://github.com/fake-staging/FAKE/releases (if needed)
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.
FAKE uses GitHub actions in build process. We have two GitHub actions; the
build_and_test action is the action triggered on PRs and pushes to
master branch. To validate changes
in a PR.
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.