Contributing¶
Any help is welcome!
If you encounter a problem using Tzolkin, 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.
- Contributing
- Report Issues (Bugs and Feature Requests)
- Forking the Repository
- Common Tasks Developing Tzolkin
- Source Code
- CodeCov Configuration
- GitHub Workflows
- GitHub Issue Template
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 Tzolkin by clicking the Fork
button in the upper right corner of the GitHub project website. Check out your fork of Tzolkin using the URL from the Code
button of your fork on Github. The URL should be something like github.com/YOUR_USERNAME/Tzolkin.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 Tzolkin¶
Jupyter Notebook¶
The Jupyter Notebook is located in the project root directory Tzolkin, named Tzolkin.ipynb
. postBuild
holds the information on how to customize the MyBinder Docker image for the use with F#.
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 Tzolkin 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 innav
Which you may need to edit
nav:
- Home: index.md
- Project Links:
- "GitHub Project Page": "https://github.com/Release-Candidate/Tzolkin"
- "Nuget Package": "https://www.nuget.org/packages/Tzolkin/"
- "Report a Bug or a Feature Request": "https://github.com/Release-Candidate/Tzolkin/issues/new/choose"
- "Issue Tracker at GitHub": "https://github.com/Release-Candidate/Tzolkin/issues"
- "Installation & Usage":
- "Installation & Usage": usage.md
- "NuGet Package": nuget_package.md
- License: license.md
- Contributing:
- Contributing: contributing.md
docs/
the markdown files that are used to generate the
HTML sites in the directorysites/
Read the Docs Configuration¶
.readthedocs.yaml
the configuration for Read the Docsdocs/requirements.txt
the packages needed by MkDocs
when generating the documentation at Read the Docs.
Locally needed packages are configured inPipfile
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.
- 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
- Download and install (“restore”) the Paket Nuget packages.
dotnet paket restore
- Delete the file
build.fsx.lock
and run Fake, to download and install (restore) it’s nuget packages.
dotnet fake run build.fsx
- 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 filePipfile
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 and Tests¶
The sources of the projects are located in the directors src
, the tests in tests
. Fabulous is used as the F# MVU wrapper of Xamarin forms.
Source¶
There are 4 projects in Tzolkin:
TzolkinDate
- the F# library and NuGet package that does the actual calculations, see NUget Package for usage information.Tzolkin
- the Tzolkin smartphone app, the platform independent part of the smartphone app.Tzolkin.iOS
- the iOS specific part of the smartphone app.Tzolkin.Android
- the Android specific part of the app.
Test Source¶
The project TestTzolkin
in the directory tests/TestTzolkin
: tests the NuGet package library, the project TzolkinDate
.
Files:
TestMain.fs
- Expecto’s main entry point when called as an executable and not by usingdotnet test
.Generics.fs
- generic functions used by the actual test functions.TestTzolkinNumber.fs
- tests the moduleTzolkinNumber
TestTzolkinGlyph.fs
- tests the moduleTzolkinGlyph
TestTzolkinDate.fs
- tests the moduleTzolkinDate
Build Targets¶
The Nuget package Tzolkin and the tests can be build using Fake, for anything smartphone related you need to use Visual Studio or Monodevelop, I did not succeed porting these projects to Paket and Fake.
- NuGet packages generated by the target
Packages
are saved to the directorynuget
, set using the expression
packageOutputPath
inbuild.fsx
. - The test results of the targets
Tests
andTestsDeb
are saved as.xml
files in the
directorytest_results
, set using the expressiontestOutputPath
inbuild.fsx
. - The coverage report
coverage.xml
of the targetsTestsCoverage
andTestsCoverageDeb
is saved to the directorytest_results
, set using the expressiontestOutputPath
inbuild.fsx
. - The output of the
Publish
target is copied to the directorybin
, set using the expressionexeOutPath
inbuild.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 GitBuild
andBuildDeb
build the configured projects
usingdotnet build
. Without suffix a release build is made,BuildDeb
uses the
debug configuration. Default is to build all projects found in the directories
src
andtests
. The expressionbuildProjs
inbuild.fsx
defines
the projects to build.Docs
generates the HTML documentation using MkDocs. The HTML is created in the directorysites
.
The output directory is configured in the MkDocs config filemkdocs.yml
Lint
runs FSharpLint on all configured projects. Default is all projects,lintProjs
inbuild.fsx
defines the projects to runLint
on.Tests
andTestsDeb
build and run all test projects in the directorytests
usingdotnet test
.
Without suffix a release build is made,TestsDeb
uses the debug configuration.
Default is testing all projects in the directorytests
,testProjs
inbuild.fsx
defines the projects to runTests
andTestsDeb
on.TestsCoverage
andTestsCoverageDeb
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 directorytests
,testProjs
inbuild.fsx
defines the projects to runTestsCoverage
andTestsCoverageDeb
on.Publish
runsdotnet publish
on the configured projects, default is all insrc
. 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
inbuild.fsx
defines the projects to runPublish
on.
Published binaries are saved to the directorybin
.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
inbuild.fsx
defines the projects to runPackages
on.
Packages are saved to the directorypackages
Upload
uploads all packages in the directorypackages
to NuGet.org. The NuGet API key
needs to be saved to the configuration using
nuget setApiKey API_KEY
Release
is a pseudo-target, the same asBuild
,Docs
,Publish
,Packages
andUpload
. 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 asBuild
andDocs
,
Usage:
dotnet fake run build.fsx target TARGET VERSION_STRING
TARGET
is the name of the target to call, see above list for possible targetsVERSION_STRING
is the version to use for the target, must be the same as the first (newest)
version in the fileCHANGELOG.md
. Targets that needVERSION_STRING
are
Packages
,Publish
,Upload
andRelease
.
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
CodeCov Configuration¶
Generate an account at CodeCov, link your GitHub repositories, add the CodeCov token
as a secret to the GitHub repositories named CODECOV_SECRET
and upload the coverage result
using a GitHub action. Used in the workflows linux_test.yml,
osx_test.yml and windows_test.yml
- name: Run Tests
run: |
cd $GITHUB_WORKSPACE
dotnet fake run ./build.fsx target TestsCoverage
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v1
if: ${{ always() }}
with:
token: ${{ secrets.CODECOV_SECRET }}
files: ./test_results/coverage.xml
directory: ./coverage/reports/
# flags: unittest
env_vars: OS,PYTHON
name: Linux-Test-Src
fail_ci_if_error: false
path_to_write_report: ./coverage/codecov_report.txt
verbose: true
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, runsdotnet publish
and
generates a new GitHUb release with these files appended. Run automatically after tagging
the source with a release tag of the formv?.?.?
(must be the same version as the newest in CHANGELOG.md).
Appends the newest entry in CHANGELOG.md to the release - scriptscripts/get_changelog.sh
See the latest release as an examplelinux_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 templatefeature_request.md
Feature request template