forked from EvergreenCrypto/dfi-docs
Migrate (and update) docs from 'docker-finance' repo to 'dfi-docs' repo
- Moves all documentation to this repository - Updates markdown to reflect latest impl - Updates assets to reflect latest impl * Assets are also now more self-documenting * Adds utility script to create gif examples
This commit is contained in:
95
markdown/How-do-I-contribute.md
Normal file
95
markdown/How-do-I-contribute.md
Normal file
@@ -0,0 +1,95 @@
|
||||
|
||||
[//]: # (docker-finance | modern accounting for the power-user)
|
||||
[//]: # ()
|
||||
[//]: # (Copyright [C] 2021-2025 Aaron Fiore [Founder, Evergreen Crypto LLC])
|
||||
[//]: # ()
|
||||
[//]: # (This program is free software: you can redistribute it and/or modify)
|
||||
[//]: # (it under the terms of the GNU General Public License as published by)
|
||||
[//]: # (the Free Software Foundation, either version 3 of the License, or)
|
||||
[//]: # ([at your option] any later version.)
|
||||
[//]: # ()
|
||||
[//]: # (This program is distributed in the hope that it will be useful,)
|
||||
[//]: # (but WITHOUT ANY WARRANTY; without even the implied warranty of)
|
||||
[//]: # (MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the)
|
||||
[//]: # (GNU General Public License for more details.)
|
||||
[//]: # ()
|
||||
[//]: # (You should have received a copy of the GNU General Public License)
|
||||
[//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
|
||||
|
||||
# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
|
||||
|
||||
- **[How do I contribute?](#how-do-i-contribute)**
|
||||
* [Donate](#donate)
|
||||
* [Development](#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](How-do-I-connect.md). Come, make this project your own!
|
||||
|
||||
#### Dependencies
|
||||
|
||||
If you like docker-finance, please consider donating to the [wonderful projects](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.yaml) that it relies upon.
|
||||
|
||||
### Development
|
||||
|
||||
Developers: your work won't go unnoticed or unappreciated. [Bounties are also available](How-do-I-connect.md).
|
||||
|
||||
When developing any part of the codebase, you'll greatly benefit from building the [`dev-tools` image](What-does-it-do.md#image-dev-tools).
|
||||
|
||||
When developing with the [`finance` image](What-does-it-do.md#image-finance), 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](How-do-I-use-it.md#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](https://gitea.com/EvergreenCrypto/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`](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/plugins) and [`container/plugins`](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/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](https://google.github.io/styleguide/shellguide.html)
|
||||
- [C++](https://google.github.io/styleguide/cppguide.html)
|
||||
- [PHP](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/ruleSets/PhpCsFixer.rst)
|
||||
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](https://gitea.com/EvergreenCrypto/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](How-do-I-use-it.md#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](How-do-I-get-started.md#client-host-configuration) file is read.
|
||||
- The `.C` files you see in the repository are ROOT.cern macro files, not C-language files.
|
||||
|
||||
[//]: # (vim: sw=2 sts=2 si ai et)
|
||||
Reference in New Issue
Block a user