Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/totallymoney/dynamodb.ok

Functional wrapper around AWS DynamoDB client in F#
https://github.com/totallymoney/dynamodb.ok

aws aws-dynamodb dynamodb fsharp functional functional-programming result-type

Last synced: 3 days ago
JSON representation

Functional wrapper around AWS DynamoDB client in F#

Awesome Lists containing this project

README 

        
# DynamoDb.Ok



## How to get started



1. Add links to GH project in all places marked `TODO: ADD_LINK`

2. Add name of the author in all places marked `TODO: ADD_AUTHOR`

3. Search for any other places marked with `TODO:` (especially in `build.fsx` script)



## What's included



* Paket, FAKE, and Fornax added as `dotnet` local tools (`.config/dotnet-tools.json`)

* `build.fsx` file, containing default FAKE script with targets for building, testing, documentation generation, publishing to GitHub, and publishing to NuGet

* `paket.dependencies` with basic set of dependencies

* `src` folder containing 2 projects - one class library (`netstandard2.0`), and CLI tool (`netcoreapp3.1`)

* `test` folder containing UnitTest project using Expecto and FsCheck

* `docs` folder with Fornax documentation template that will generate nice documentation for your project.

* `.devcontainer` folder with definition of [Development Container](https://code.visualstudio.com/docs/remote/containers)

* `.github/workflows` folder with definition for 3 GitHub actions - one for building and testing code as CI, one for creating new GH releases on new tags, one for deploying documentation when new tag is pushed. To use latter, you need to define `PERSONAL_TOKEN` secret in GitHub repo settings with Personal Access Token.

* `.github/ISSUE_TEMPLATE` folder with 2 different issue templates - one for bug report, other one for feature request



## How to build application



1. Make sure you've installed .Net Core version defined in [global.json](global.json)

2. Run `dotnet tool restore` to install all developer tools required to build the project

3. Run `dotnet fake build` to build default target of [build script](build.fsx)

4. To run tests use `dotnet fake build -t Test`

5. To build documentation use `dotnet fake build -t Docs`



## How to work with documentation



1. Make sure you've installed .Net Core version defined in [global.json](global.json)

2. Run `dotnet tool restore` to install all developer tools required to build the project

3. Run `dotnet fake build` to build default target of [build script](build.fsx)

4. Build documentation to make sure everything is fine with `dotnet fake build -t Docs`

5. Go to docs folder `cd docs` and start Fornax in watch mode `dotnet fornax watch`

6. You documentation should be now accessible on `localhost:8080` and will be regenerated on every file save



## How to release.



#### Releasing as part of the CI



1. Update [CHANGELOG.md](./CHANGELOG.md) by adding new entry (`## [X.Y.Z]`) and commit it.

2. Create version tag (`git tag vX.Y.Z`)

3. Run `dotnet fake build -t Pack` to create the nuget package and test/examine it locally.

4. Push the tag to the repo `git push origin vX.Y.Z` - this will start CI process that will create GitHub release and put generated NuGet packages in it

5. Upload generated packages into NuGet.org



#### Releasing from local machine



In case you don't want to create releases automatically as part of the CI process, we provide also set of helper targets in `build.fsx` script.

Create release.cmd or release.sh file (already git-ignored) with following content (sample from `cmd`, but `sh` file should be similar):



```

@echo off

cls



SET nuget-key=YOUR_NUGET_KEY

SET github-user=YOUR_GH_USERNAME

SET github-pw=YOUR_GH_PASSWORD_OR_ACCESS_TOKEN



dotnet fake build --target Release

```



## Documentation Theme



Template includes, out-of-the-box, nice theme for your project documentation, which integrates with FSharp.Formatting to create also API reference



* Sample documentation produced by the template can be found on http://kcieslak.io/SampleDynamoDb.Ok.

* Created theme is partial port to Fornax of [Hugo Learn theme](https://learn.netlify.com/en/).

* You define content as markdown files

* Menu navigation based on the documentation system described on https://documentation.divio.com/

* Use FSharp.Formatting to create API reference for the project - sample: http://kcieslak.io/SampleDynamoDb.Ok/Reference/ApiRef.html

* Use [Lunr.js](https://lunrjs.com/) to provide client side search based on generated by Fornax search index - sample: try searching for `Lorem` or `Sample` in search available on http://kcieslak.io/SampleDynamoDb.Ok

* Use [Mermaid.js](https://mermaid-js.github.io/mermaid/#/) to provide client side render diagrams and graphs - sample: http://kcieslak.io/SampleDynamoDb.Ok/diagrams.html



## How to contribute



*Imposter syndrome disclaimer*: I want your help. No really, I do.



There might be a little voice inside that tells you you're not ready; that you need to do one more tutorial, or learn another framework, or write a few more blog posts before you can help me with this project.



I assure you, that's not the case.



This project has some clear Contribution Guidelines and expectations that you can [read here](CONTRIBUTING.md).



The contribution guidelines outline the process that you'll need to follow to get a patch merged. By making expectations and process explicit, I hope it will make it easier for you to contribute.



And you don't just have to write code. You can help out by writing documentation, tests, or even by giving feedback about this work. (And yes, that includes giving feedback about the contribution guidelines.)



Thank you for contributing!



## Contributing and copyright



The project is hosted on [GitHub](TODO: ADD_LINK) where you can report issues, fork

the project and submit pull requests.



The library is available under [MIT license](LICENSE.md), which allows modification and redistribution for both commercial and non-commercial purposes.



Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.