diff --git a/.idea/.idea.Emulsion/.idea/dictionaries/fried.xml b/.idea/.idea.Emulsion/.idea/dictionaries/fried.xml index 33af0d3f..e0dccf6c 100644 --- a/.idea/.idea.Emulsion/.idea/dictionaries/fried.xml +++ b/.idea/.idea.Emulsion/.idea/dictionaries/fried.xml @@ -4,6 +4,7 @@ andivionian aquana codingteam + efcore fhtagn maintainership diff --git a/CHANGELOG.md b/CHANGELOG.md index d1eb1c39..f2d20c6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning v2.0.0](https://semver.org/spec/v2.0.0.html). -When considering the public API, we take into account the tool configuration and external requirements of the framework-dependent binary. Meaning that basically, breaking changes in configurations or in the runtime requirements should be causing a major version increment. +When considering the public API, we take into account the tool configuration and external requirements of the framework-dependent binary. Meaning that basically, breaking changes in configuration files, command-line syntax, or in the runtime requirements should be causing a major version increment. ## [Unreleased] (3.0.0) ### Changed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..deff3b4c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +Contributor Guide +================= + +Prerequisites +------------- +To develop Emulsion, make sure you've installed the following tools: +- [.NET SDK][dotnet] 8.0 or later, +- [Node.js][node.js] 18: + - if you use [nvm][] or [nvm-windows][], then run `nvm use 18`. + +Build +----- +Build the project using the following shell command: + +```console +$ dotnet build +``` + +Run +--- +Run the application from sources using the following shell command: + +```console +$ dotnet run --project ./Emulsion [optional-path-to-json-config-file] +``` + +Test +---- +Execute the tests using the following shell command: + +```console +$ dotnet test +``` + +Docker Publish +-------------- +To build and push the container to Docker Hub, use the following shell commands: + +```console +$ docker build -t codingteam/emulsion:$EMULSION_VERSION \ + -t codingteam/emulsion:latest . + +$ docker login # if necessary +$ docker push codingteam/emulsion:$EMULSION_VERSION +$ docker push codingteam/emulsion:latest +``` + +where `$EMULSION_VERSION` is the version of the image to publish. + +Updating the Database Structure +------------------------------- +If you want to update a database structure, you'll need to create a migration. + +This article explains how to create a database migration using [EFCore.FSharp][efcore.fsharp]. + +1. Change the entity type (see `Emulsion.Database/Entities.fs`), update the `EmulsionDbContext` if required. +2. Run the following shell commands: + + ```console + $ dotnet tool restore + $ cd Emulsion.Database + $ dotnet ef migrations add + ``` + +[dotnet]: https://dot.net/ +[efcore.fsharp]: https://github.com/efcore/EFCore.FSharp +[node.js]: https://nodejs.org/ +[nvm]: https://github.com/nvm-sh/nvm +[nvm-windows] diff --git a/Emulsion.sln b/Emulsion.sln index a5d4abc1..54554293 100644 --- a/Emulsion.sln +++ b/Emulsion.sln @@ -16,6 +16,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Dockerfile = Dockerfile MAINTAINERSHIP.md = MAINTAINERSHIP.md Directory.Build.props = Directory.Build.props + CONTRIBUTING.md = CONTRIBUTING.md EndProjectSection EndProject Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "Emulsion.Tests", "Emulsion.Tests\Emulsion.Tests.fsproj", "{1B3B65DD-FD58-45FA-B6FF-8532B513A7D9}" @@ -36,11 +37,6 @@ ProjectSection(SolutionItems) = preProject .config\dotnet-tools.json = .config\dotnet-tools.json EndProjectSection EndProject -Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{12336258-82C7-4C09-A73F-8D0B146578B2}" -ProjectSection(SolutionItems) = preProject - docs\create-migration.md = docs\create-migration.md -EndProjectSection -EndProject Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "Emulsion.ContentProxy", "Emulsion.ContentProxy\Emulsion.ContentProxy.fsproj", "{A520FD41-A1CB-4062-AFBC-62A8BED12E81}" EndProject Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "Emulsion.Web", "Emulsion.Web\Emulsion.Web.fsproj", "{8EFD8F6C-43D3-4CE0-ADB8-63401E4A64FE}" diff --git a/README.md b/README.md index b54ad28b..0661894a 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,18 @@ Installation There are two supported Emulsion distributions: as a framework-dependent .NET application, or as a Docker image. ### .NET Application -To run Emulsion as [a framework-dependent .NET application][docs.dotnet.framework-dependent], you'll need to [install .NET runtime][dotnet.install] version 8.0 or later. +To run Emulsion as [a framework-dependent .NET application][docs.dotnet.framework-dependent], you'll need to [install .NET runtime][dotnet] version 8.0 or later. Then, download the required version in the [Releases][releases] section. -After that, configure the application, and start it using the following shell command: +After that, configure the application (see the following section), and start it using the following shell command: ```console -$ dotnet Emulsion.dll +$ dotnet Emulsion.dll [optional-path-to-json-config-file] ``` +If `optional-path-to-json-config-file` is not provided, Emulsion will use the `emulsion.json` file from the current directory. + ### Docker It is recommended to use Docker to deploy this application. To install the application from Docker, you may use the following Bash script: @@ -47,18 +49,8 @@ where - `$DATA` is the absolute path to the data directory (used by the configuration) - `$WEB_PORT` is the port on the host system which will be used to access the content proxy -Build ------ - -Install [.NET SDK][dotnet] 8.0 and Node.js 18 or newer for your platform, then run: - -```console -$ dotnet build -``` - -Configure ---------- - +Configuration +------------- Copy `emulsion.example.json` to `emulsion.json` and set the settings. For some settings, there are defaults: ```json @@ -130,62 +122,22 @@ Current configuration system allows the following: 2. When receiving a piece of Telegram content (a file, a photo, an audio message), the bot will send a link to `https://example.com/telegram/content/` to the XMPP chat. 3. When anyone visits the link, the reverse proxy will send a request to `http://localhost/content/`, which will take a corresponding content from the database. -Test ----- - -To execute the tests: - -```console -$ dotnet test -``` - -Run ---- - -Requires [.NET Runtime][dotnet] version 8.0 or newer. - -```console -$ dotnet run --project ./Emulsion [optional-path-to-json-config-file] -``` - -Docker Publish --------------- -To build and push the container to Docker Hub, use the following commands: - -```console -$ docker build -t codingteam/emulsion:$EMULSION_VERSION \ - -t codingteam/emulsion:latest . - -$ docker login # if necessary -$ docker push codingteam/emulsion:$EMULSION_VERSION -$ docker push codingteam/emulsion:latest -``` - -where `$EMULSION_VERSION` is the version of the image to publish. - Documentation ------------- - -Common documentation: - - [Changelog][docs.changelog] +- [Contributor Guide][docs.contributing] - [License (MIT)][docs.license] - -Developer documentation: - -- [How to Create a Database Migration][docs.create-migration] - [Maintainership][docs.maintainership] [andivionian-status-classifier]: https://github.com/ForNeVeR/andivionian-status-classifier#status-aquana- [badge.docker]: https://img.shields.io/docker/v/codingteam/emulsion?sort=semver [docker-hub]: https://hub.docker.com/r/codingteam/emulsion [docs.changelog]: ./CHANGELOG.md -[docs.create-migration]: ./docs/create-migration.md +[docs.contributing]: CONTRIBUTING.md [docs.dotnet.framework-dependent]: https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-framework-dependent [docs.license]: ./LICENSE.md [docs.maintainership]: MAINTAINERSHIP.md -[dotnet.install]: https://dot.net -[dotnet]: https://dotnet.microsoft.com/download +[dotnet]: https://dot.net/ [hashids.net]: https://github.com/ullmark/hashids.net [releases]: https://github.com/codingteam/emulsion/releases [status-aquana]: https://img.shields.io/badge/status-aquana-yellowgreen.svg diff --git a/docs/create-migration.md b/docs/create-migration.md deleted file mode 100644 index a08ed419..00000000 --- a/docs/create-migration.md +++ /dev/null @@ -1,15 +0,0 @@ -How to Create a Database Migration -================================== - -This article explains how to create a database migration using [EFCore.FSharp][efcore.fsharp]. - -1. Change the entity type (see `Emulsion.Database/Entities.fs`), update the `EmulsionDbContext` if required. -2. Run the following shell commands: - - ```console - $ dotnet tool restore - $ cd Emulsion.Database - $ dotnet ef migrations add - ``` - -[efcore.fsharp]: https://github.com/efcore/EFCore.FSharp