Contributing

Any help is welcome!

If you encounter a problem using TzolkinWaves, a task it not as easy as you’d like it to be or you’d like something added to it: open an issue at GitHub, see section Report Issues.

Report Issues (Bugs and Feature Requests)

File a bug report at Github.

Add a feature request at Github.

Take a look at the Issue Tracker at GitHub

Forking the Repository

If you’d like to contribute directly, e.g. better the documentation, add another language or write some source code: fork TzolkinWaves by clicking the Fork button in the upper right corner of the GitHub project website. Check out your fork of TzolkinWaves using the URL from the Code button of your fork on Github. The URL should be something like github.com/YOUR_USERNAME/TzolkinWaves.git.

Details about how to fork a repository on Github are here.

Make your changes, push them to your forked repository and make a pull-request (e.g. using the Pull request-button above and right of GitHubs source file view).

See GitHub on Pull-Requests and another How-To.

Github Documentation on Collaborating with Issues and Pull Requests

See GitHub’s documentation about how to contribute for details: Collaborating with issues and pull requests.

Common Tasks Developing TzolkinWaves

Changing and Generating Documentation

Installing Dependencies

To generate the documentation using MkDocs, a virtual Python environment is needed.
So, first you need to install Python, if you don’t
have it installed already - either from your distributions repository, using the XCode or Homebrew version, or getting it from Python.org.

See

In the file Pipfile there is a stanza saying

[requires]
python_version = "3.9"

That’s just because I used 3.9 when generating that
documentation, and Pipenv is picky about the version mentioned
there. Just edit that to match your installed
Python version.

Install pipenv using the package manager pip

pip install pipenv

Now you’re ready to download and install the needed packages using pipenv

pipenv install --dev

After that you can use MkDocs.

Call

pipenv run mkdocs serve

in the root directory of TzolkinWaves and connect to the running webserver at http://127.0.0.1:8000.
This preview shows changes in realtime, so any changes to the markdown files in docs you
see as preview as soon as you save the file. The generated HTML files are saved in the directory
sites.

MkDocs Files

  • mkdocs.yml the MkDocs configuration, specially
    the configuration of the navigation sidebar in nav
    Which you may need to edit
     nav:
      - Home: index.md
      - Project Links:
          - "Downloads": https://github.com/Release-Candidate/TzolkinWaves/releases/latest
          - "GitHub Project Page": "https://github.com/Release-Candidate/TzolkinWaves"
          - "Report a Bug or a Feature Request": "https://github.com/Release-Candidate/TzolkinWaves/issues/new/choose"
          - "Issue Tracker at GitHub": "https://github.com/Release-Candidate/TzolkinWaves/issues"
      - "Installation & Usage":
          - "Installation & Usage": usage.md
          - License: license.md
      - Contributing:
          - Contributing: contributing.md
  • docs/ the markdown files that are used to generate the
    HTML sites in the directory sites/

Read the Docs Configuration

  • .readthedocs.yaml the configuration for Read the Docs
  • docs/requirements.txt the packages needed by MkDocs
    when generating the documentation at Read the Docs.
    Locally needed packages are configured in Pipfile

Read the Docs automatically generates the MkDocs documentation after each git push.

GitHub Documentation

The Markdown documentation for GitHub are the files README.md and CHANGELOG.md in the project root directory.

Source Code

Before you can use the configured Tools of this project, you have to download and install (aka. restore) the packages
of the tools.

  1. First, download and install the “dotnet tools” using the command
dotnet tool restore

now you have installed Fake, Paket and FSharpLint,
configured in the file .config/dotnet-tools.json

  1. Download and install (“restore”) the Paket Nuget packages.
dotnet paket restore
  1. Delete the file build.fsx.lock and run Fake, to download and install (restore) it’s nuget packages.
dotnet fake run build.fsx
  1. To generate the documentation using MkDocs, a virtual Python environment is needed. A virtual Python
    environment is the same as the locally installed Nuget packages above.
    So, first you need to install Python, if you don’t
    have it installed already - either from your distributions repository, using the XCode or Homebrew version,
    or getting it from Python.org.
    In the file Pipfile there is a stanza saying
[requires]
python_version = "3.9"

That’s just because I used 3.9 when generating that
documentation, and Pipenv is picky about the version mentioned
there. Just edit that to match your installed
Python version.
Install pipenv using the package
manager pip

pip install pipenv

Now you’re ready to download and install the needed packages using pipenv

pipenv install --dev

Source Code

The sources of the projects are located in the directors src.

Source

There is 1 project in TzolkinWaves/src:

  • TzolkinWaves - the TzolkinWaves program, the GUI.

Build Targets

The projects can be build using an IDE (Visual Studio or JetBRains Rider), directly using dotnet build/test/run and using Fake.

  • NuGet packages generated by the target Packages are saved to the directory nuget, set using the expression
    packageOutputPath in build.fsx.
  • The test results of the targets Tests and TestsDeb are saved as .xml files in the
    directory test_results, set using the expression testOutputPath in build.fsx.
  • The coverage report coverage.xml of the targets TestsCoverage and TestsCoverageDeb
    is saved to the directory test_results, set using the expression testOutputPath
    in build.fsx.
  • The output of the Publish target is copied to the directory bin, set using the expression exeOutPath in build.fsx.

Warning

All of these directories are cleaned - that means all files in them are deleted - using the target clean.
Which is called as the first build step of all targets. In other words: all generated
files (including Nuget packages) are deleted when calling any target.

The Fake script build.fsx defines the following targets:

  • Clean deletes all files generated by the build. This is called first in every other target, all generated files are deleted before running any target!
  • Distclean deletes everything that isn’t checked in to Git
  • Build and BuildDeb build the configured projects
    using dotnet build. Without suffix a release build is made, BuildDeb uses the
    debug configuration. Default is to build all projects found in the directories
    src and tests. The expression buildProjs in build.fsx defines
    the projects to build.
  • Docs generates the HTML documentation using MkDocs. The HTML is created in the directory sites.
    The output directory is configured in the MkDocs config file mkdocs.yml
  • Lint runs FSharpLint on all configured projects. Default is all projects, lintProjs in build.fsx
    defines the projects to run Lint on.
  • Tests and TestsDeb build and run all test projects in the directory tests using dotnet test.
    Without suffix a release build is made, TestsDeb uses the debug configuration.
    Default is testing all projects in the directory tests, testProjs in build.fsx defines the projects to run Tests and TestsDeb on.
  • TestsCoverage and TestsCoverageDeb build and run all tests projects and generate a coverage report using AltCover.
    With and without suffix a debug configuration is build and tested.
    Default is testing all projects in the directory tests, testProjs in build.fsx defines the projects to run TestsCoverage and TestsCoverageDeb on.
  • Publish runs dotnet publish on the configured projects, default is all in src. The
    build is done with the release configuration, the version must be given as argument on the command line
    and be the same as the newest one in CHANGELOG.md.
    publishProjs in build.fsx defines the projects to run Publish on.
    Published binaries are saved to the directory bin.
  • Packages builds the NuGet packages of all projects using a release build. The
    build is done with the release configuration, the version must be given as argument on the command line
    and be the same as the newest one in CHANGELOG.md.
    packageProjs in build.fsx defines the projects to run Packages on.
    Packages are saved to the directory packages
  • Upload uploads all packages in the directory packages to NuGet.org. The NuGet API key
    needs to be saved to the configuration using
  • Run builds the program and runs it using dotnet run -p PROJECT_FILE.
nuget setApiKey API_KEY
  • Release is a pseudo-target, the same as Build, Docs, Publish, Packages and Upload. The
    build is done with the release configuration, the version must be given as argument on the command line
    and be the same as the newest one in CHANGELOG.md.
  • All is a pseudo-target, the same as Build and Docs,

Usage:

dotnet fake run build.fsx target TARGET VERSION_STRING
  • TARGET is the name of the target to call, see above list for possible targets
  • VERSION_STRING is the version to use for the target, must be the same as the first (newest)
    version in the file CHANGELOG.md. Targets that need VERSION_STRING are
    Packages, Publish, Upload and Release.

Run all default targets (see above):

dotnet fake run build.fsx

Which is the same as

dotnet fake run build.fsx target All

E.g. to build a debug version of all projects:

dotnet fake run build.fsx target BuildDeb

Generate the Nuget packages of version 2.65.93 and upload to NuGet.org

dotnet fake run build.fsx target Upload 2.65.93

Run dotnet publish on the configured projects (publishProjs in build.fsx) setting the
version to 6.2.53

dotnet fake run build.fsx target Publish 6.2.53

Run the tests - result is in the directory test_results:

dotnet fake run build.fsx target Tests

Run the tests with coverage analysis - result is in the directory test_results:

dotnet fake run build.fsx target TestsCoverage

GitHub Workflows

All tests and builds are executed on Linux,
Mac OS X and Windows.

These are the GitHub workflows defined in the directory .github/workflows

  • create_packages.yml creates and uploads the NuGet packages, runs dotnet publish and
    generates a new GitHUb release with these files appended. Run automatically after tagging
    the source with a release tag of the form v?.?.? (must be the same version as the newest in CHANGELOG.md).
    Appends the newest entry in CHANGELOG.md to the release - script scripts/get_changelog.sh
    See the latest release as an example
  • linux_test.yml runs the tests and coverage tests on Linux, uploads the test results as artifacts,
    uploads the coverage results to CodeCov.
  • osx_test.yml runs the tests and coverage tests on Mac OS X, uploads the test results as artifacts,
    uploads the coverage results to CodeCov.
  • windows_test.yml runs the tests and coverage tests on Windows, uploads the test results as artifacts,
    uploads the coverage results to CodeCov.

The badges of the workflows are linked in the section Badges

GitHub Issue Template

Issue templates for GitHub in .github/ISSUE_TEMPLATE/

  • bug_report.md Bug report template
  • feature_request.md Feature request template