Skip to content

Latest commit

 

History

History
110 lines (86 loc) · 5.58 KB

CONTRIBUTING.md

File metadata and controls

110 lines (86 loc) · 5.58 KB

Development of MeshTools package

If you would like to modify MeshTools package yourself or contribute back to the original repository, then the following instructions can help you. First you need to install Git and clone the project from its GitHub homepage to your local computer.

You will need:

  • Mathematica version 11.1 or later.
  • Wolfram Workbench for building documentation.
  • WolframScript for building the .paclet file from command line. On most systems it already comes bundled with Mathematica installation.

Testing code

It is considered good practice that every (public) function in this package includes its own set of unit tests. A bunch of them is collected in Tests/Tests.wl file, using the Mathematica testing framework. It is recommended that you run them periodically during development and especially before every commit. This can be done by calling script file Tests/RunTests.wls in command line (from repository root directory) or by evaluating whole notebook Tests/RunTests.nb.

Make sure that all tests pass on the earliest supported version of Mathematica (currently version 10.0).

Integration of tests in Git hook

Unit test can be run automatically before every commit via Git client-side hooks. File pre-commit should contain call to Tests/RunTests.wls script, which exits with value 0 if all tests pass and aborts the commit otherwise. Minimal example of pre-commit file content is:

#!/bin/sh
./Tests/RunTests.wls

Building the package

Package building covers procedures to convert contents of repository to .paclet file which can be installed by the users. This is done by the build script included in the repository, which can be run from command line (terminal) with Build.wls. On Unix-like operating systems it may be necessary to set executable permissions first with chmod a+x Build.wls. For more information see also wolframscriptdocumentation.

Documentation

The package documentation comes in a form of notebooks with textual explanation and executable code examples. Raw documentation notebooks are created and processed with additional software Wolfram Workbench.

Before manipulating documentation for the first time, you have to import the project into Workbench. This procedure needs to be done only once.

  • From the menu bar, select File > Open Project from File System.
  • In the Import wizard, select MeshTools repository root directory for the input field "Import source:".
  • You can leave all checkboxes as default and click Finish.
  • MeshTools directory tree now appears in "Package Explorer" tab (on the left side).

For more information about adding and modifying documentation notebooks, please see Wolfram Workbench documentation.

Documentation build procedure refers to the process of taking "source" notebooks and converting them to form suitable for Mathematica documentation centre. For example Graphics objects are rasterized to minimize documentation file size. To build documentation follow these steps:

  • From the Workbench menu bar, select Window > Show View > Application Tools.
  • In the "Application Tools" tab select MeshTools in project drop down list.
  • Click on button "Build", just bellow the drop down list.
  • Build procedure may take a few minutes and copies processed notebooks to "build" subdirectory in repository root directory.
  • You can also see the result of procedure after it is completed by clicking button "Preview" in "Application Tools" tab.

Creating a .paclet file

Running the build script in command line from repository root directory will automatically create a MeshTools-X.Y.Z.paclet file in the "build" folder. Keep in mind that you have to build documentation with Workbench before creating the paclet.

Script option --install will also install it locally to $UserBasePacletsDirectory. Option --release adds metadata to indicate a proper public releases.

Release checklist

The following tasks should be performed for successful release of a new public version of the package.

  • Check if all known bugs have been fixed.
  • Check if all changes in functionality since the previous release have been documented (use git log --oneline to refresh memory).
  • Run a full suite of automated tests.
  • Build the package along with documentation and test if installed version works ok (e.g. documentation examples). You can send this version to other test users for additional feedback.
  • Update PacletInfo.m with a new version number. It should be determined according to semantic versioning principles.
  • Update README.md and CHANGELOG.md with relevant changes.
  • Make a new git tag with corresponding version number and push it to remote repository.
  • Build a public version with --release option of build script.
  • Create a new release on GitHub releases page and attach there resulting .paclet file.
  • Inform users about a new version (email, website, etc).
  • Celebrate.