dfi-docs/markdown/How-do-I-contribute.md

• How do I contribute?
  • Donate
  • Development

How do I contribute?

There are multiple ways to contribute. All contributions are welcome!

Donate

Time

Your input while using docker-finance is valuable and appreciated. Come, make this project your own!

Dependencies

If you like docker-finance, please consider donating to the wonderful projects that it relies upon.

Development

Developers: your work won't go unnoticed or unappreciated. Bounties are also available.

When developing any part of the codebase, you'll greatly benefit from building the dev-tools image.

When developing with the finance image, you can create a development profile with the gen command argument dev=on. From there, you'll have access to mockup CSVs as described in Flow Layout.

• In addition to dev=on, run the confirm=off and profile= arguments to quickly spin-up a new development profile
• Developer mockup CSVs can be found in the mockup directories within the hledger-flow section of the docker-finance repository
• Developer mockup CSVs will intentionally have multiple years within in a 1-in/year directory in order to test for year parsing

When developing non-code documentation, please work with the dfi-docs repository.

Plugins

Plugins allow you to use docker-finance public APIs, libraries and environment (client and/or container) to meet your unique needs. These plugins are categorical; as in, there are client-side ("custom") plugins and repository ("repo") plugins. Additionally, there are subcategories such as docker, finance and root (respective to their modules).

Client-side custom plugins allow you to drop-in any code that you write and keep them locally. Repository plugins are plugins that remain within the repository and will require a pull request for any changes to be made. Client-side custom plugins can be used for either client or container modules (see directory layout).

Upon client gen, a client-side directory layout is generated. This layout consists of:

• ${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker
  • Custom plugins that function only client-side (lib_docker)
• ${DOCKER_FINANCE_CLIENT_PLUGINS}/container/{finance,root}
  • Custom plugins that function only container-side (lib_finance, root)

WARNING: don't change the parent client-side directory layout (although, you can add subdirectories):

• e.g., ${DOCKER_FINANCE_CLIENT_PLUGINS}/container/finance/my_experimental_plugins/{file1.ext,file2.ext}

This client-side "custom" layout somewhat mirrors the repository's plugins layout (see client/plugins and container/plugins).

For more information, see the example plugins and help usage of each module, e.g.; plugins help or help().

Note: for custom plugins within directory docker and finance that utilize the shell, any language can be used so long as the file is executable, reads the shell environment and can initiailize their respective libraries (lib_docker, lib_finance).

Pull Request

Before sending a pull request:

1. If you created a new file, please run the dev-tools' license file=/path/to/new/file.ext command to update the copyright date and author.
2. For any work that can be linted, utilize the dev-tools image (e.g., dfi dev-tools/${USER}:default linter type=bash,php,c++).
   • See linter help for details.
3. As for style guidelines, these are recommended:
   • Bash
   • C++
     • Ignore their rule for no throw'ing / no exceptions
   • PHP
4. If you can, please document the code in Doxygen style where applicable and run doxygen gen to see your code documentation.

Any non-code documentation should go into the dfi-docs repository.

Notes

• Regarding client configuration, Docker volumes aren't used because of chicken-or-the-egg problem (among other reasons). docker-finance needs the client environment before building the Docker image and spawning the subsequent container (which would rely on volumes).
• As described in Mostly-Unified CLI, to use a developer version of any dfi image, simply build and tag with any tag name you'd like (e.g., dfi archlinux/${USER}:dev build type=default)
• Run DOCKER_FINANCE_DEBUG=1 dfi <platform/user:tag> <cmd> [args] to debug before the Client (Host) Configuration File file is read.
• The .C files you see in the repository are ROOT.cern macro files, not C-language files.