CONTRIBUTING.md

Contributing

• Contributing
  • Types of Contributions
    • Report Bugs
    • Fix Bugs
    • Implement Features
    • Submit Feedback
  • Get Started!
  • Pull Request Guidelines
  • Tips
    • Generating code from Markdown
    • Generate code from Markdown and vice versa
    • Generate code from Markdown on commit
  • New release

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/NLESC-JCER/cpp2wasm/issues/new?labels=bug&template=10_bug_report.md.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with "bug" is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with "enhancement" is open to whoever wants to implement it.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/NLESC-JCER/cpp2wasm/issues.

If you are proposing a feature go here.

Get Started!

Ready to contribute? Here's how to set up cpp2wasm for local development.

1. Fork the cpp2wasm repo on GitHub.

2. Clone your fork locally:

   git clone https://github.com/your_name_here/cpp2wasm.git

3. Install the dependencies as listed in INSTALL.md#dependencies.

4. Create a branch for local development::

   git checkout -b name-of-your-bugfix-or-feature

   Now you can make your changes locally.

5. Write tests where possible. Writing tests should be done in a literate way in TESTING.md

6. When you're done making changes, make sure the Markdown and source code files are entangled with

   make entangle

7. When cli/*hpp or webassembly/wasm-newtonraphson.cpp changes, the WebAssembly module also has to be rebuilt. This will require emscripten. To rebuild the WebAssembly module run:

   make build-wasm

8. Commit your changes and push your branch to GitHub::

   git add .
   git commit -m "Your detailed description of your changes."
   git push origin name-of-your-bugfix-or-feature

9. Submit a pull request through the GitHub website.

Pull Request Guidelines

See .github/PULL_REQUEST_TEMPLATE.md for guidelines.

Tips

Generating code from Markdown

The Entangled - Pandoc filters Docker image can be used to generate source code files from the Markdown files.

First, store your user id and group as environment variables:

export HOST_UID=$(id -u)
export HOST_GID=$(id -g)

Then,

docker run --rm --user ${HOST_UID}:${HOST_GID} -v ${PWD}:/data nlesc/pandoc-tangle:0.5.0 --preserve-tabs *.md

Generate code from Markdown and vice versa

Use Entangled deamon to convert code blocks in Markdown to and from source code files. Each time a Markdown code block is changed the source code files will be updated. Each time a source code file is changed the code blocks in the Markdown files will be updated.

1. Install entangled
2. Run entangled daemon with

entangled daemon

Generate code from Markdown on commit

To automatically generate code from Markdown on each commit, initialize the git hook with.

make init-git-hook

The rest of this section describes how the git hook works.

The pre-commit hook script runs entangle using Docker and adds newly written files to the current git commit.

#!/bin/sh
# this shell script is stored as .githooks/pre-commit

echo 'Check entangled files are up to date'

# Entangle Markdown to source code and store the output
LOG=$(docker run --rm --user $(id -u):$(id -g) -v ${PWD}:/data nlesc/pandoc-tangle:0.5.0 --preserve-tabs *.md 2>&1 > /dev/null)
# Parse which filenames have been written from output
FILES=$(echo $LOG | perl -ne 'print $1,"\n" if /^Writing \`(.*)\`./')
[ -z "$FILES" ] && exit 0
echo $FILES

echo 'Adding written files to commit'
echo $FILES | xargs git add

The hook must be made executable with

chmod +x .githooks/pre-commit

The git hook can be enabled with

git config --local core.hooksPath .githooks

(core.hooksPath config is available in git version >= 2.9)

New release

A reminder for the maintainers on how to create a new release.

1. Make sure all your changes are committed.
2. Verify that CHANGELOG.md has all the relevant changes. Visit releases page and click on the ?? commits to master since this release link in the latest release to see the diff between the latest release and master.
3. Verify that the authors list in CITATION.cff is up to date
4. If needed, generate updated Zenodo metadata using the cffconvert web service, then use its result to update .zenodo.json.
5. Create a GitHub release