Merge pull request #315 from POPWorldMedia/v19-prep

v19 prep

README.md

@@ -3,12 +3,12 @@
 POP Forums
 =========
 
-A forum and Q&A application with real-time updating in multiple languages.
+A forum and Q&A application with real-time updating, image uploading and private message chat in multiple languages.
 
-The main branch is now the work-in-progress for future versions running on .NET 6+. The v18.x branch is v18.x, running on .NET 6. If you're looking for the version that works on .NET Framework 4.5+ with MVC 5, check out v13.0.2.
+The main branch is now the work-in-progress for future versions running on .NET 6+. The v19.x branch is v19.x, running on .NET 6. If you're looking for the version that works on .NET Framework 4.5+ with MVC 5, check out v13.0.2.
 
 Roadmap:
-The v18 release concentrates on performance and optimization, along with significant refactoring to use modern frameworks and bug fixes. Forthcoming releases will focus on UI refinement and modernization.
+The v19 release concentrates on long awaited new feature requests, updates to the user interface and minor bug fixes.
 
 For the latest information and documentation, and how to get started, check the pages (also in markdown in /docs of source):  
 https://popworldmedia.github.io/POPForums/

docs/faq.md

@@ -26,10 +26,10 @@ Currently we have English, Spanish (es), Dutch (nl), Ukrainian (uk), Taiwanese M
 Not at all. That app served a great many different functions and was integrated with Microsoft ID's, a centralized profiling system, etc. It was/is huge. This app has its roots in the web sites I've been running for fun and profit for years, to the extent that you can find old posts on those sites from the turn of the century with all kinds of formatting failures. Those were the ASP.old days.
 
 ## I noticed you're not using [some ORM framework]. Why not?
-One of the requirements back in the day was to simply work with the existing data structures of v8.x, a Webforms app. In that sense, the data plumbing was already pretty well established and known to work, and it has followed all the way up through the Core version. My opinion is that ORM's tend to be a leaky abstraction that never work in the black box way that you would hope. I have adopted Dapper though, which covers the core use case that you're really after anyway: Mapping parameters to queries and results to objects. One doesn't have to write actual SQL all that often.
+One of the requirements back in the day was to simply work with the existing data structures of v8.x, a Webforms app. In that sense, the data plumbing was already pretty well established and known to work, and it has followed all the way up through the Core version. My opinion is that ORM's tend to be leaky abstractions that never work in the black box way that you would hope. I have adopted Dapper though, which covers the core use case that you're really after anyway: Mapping parameters to queries and results to objects. One doesn't have to write actual SQL all that often.
 
 ## You don't name your async methods with the `Async` suffix. Just who do you think you are?
-Look, when almost all of your methods are async what's the point? The only place I use it is when there are both synchronous and asynchronous methods. Your fancy IDE knows what the return type is, and the compiler lets you know when you're not awaiting. You'll be fine.
+Look, when almost all of your methods are async with no synchronous version what's the point? The only place I use it is when there are both synchronous and asynchronous methods. Your fancy IDE knows what the return type is, and the compiler lets you know when you're not awaiting. You'll be fine.
 
 ## What external frameworks are you using, and why?
 I wanted to keep external binaries to a minimum, but I'm using MailKit for email functions, ImageSharp for photo resizing, Moq for test mocking, and xUnit for unit testing. On the front end, the main app uses vanilla web components written in TypeScript, along with Bootstrap and TinyMCE. The admin area uses Vue.js. Github has that handy dependency graph now that you can look at for more information.
@@ -38,10 +38,10 @@ I wanted to keep external binaries to a minimum, but I'm using MailKit for email
 Here's the thing about a forum... it's mostly walls of text. I can tell you from the 60,000+ topics I have indexed on a couple of sites that it's super SEO friendly. To that end, the functionality of a forum is mostly making posts, which doesn't require a big library to do. That's why there are little web components spread around on little islands, and not an all-in effort to React. Heck, the admin area uses Vue.js, but even that works by way of a simple script reference.
 
 ## The unit tests suck.
-That's not a question. In porting to Core, much of the controller-level unit testing didn't come along, and it needs a lot of refactoring. Ideally, there shouldn't be so much logic in the controllers.
+That's not a question. In porting to Core, much of the controller-level unit testing didn't come along, and it needs a lot of refactoring. Ideally, there shouldn't be so much logic in the controllers, but there is still a lot there.
 
 ## What's the release roadmap?
-It has generally been my intention to keep up with the latest .NET framework versions, but getting to Core took way longer than expected. You can check the issue tracker for stuff currently in flight. The app needs a fair amount of refactoring, so that will happen over time, and hopefully enable more unit tests. I expect refinement after all of the new features of v19 get some reasonable use.
+It has generally been my intention to keep up with the latest .NET framework versions. You can check the issue tracker for stuff currently in flight. The app needs a fair amount of refactoring, so that will happen over time, and hopefully enable more unit tests. I expect refinement after all of the new features of v19 get some reasonable use.
 
 ## Can I contribute?
 I very much welcome translations of the `.resx` files, so send a pull request for those immediately! If someone really digs into the source code and understands it in a non-trivial way, then yes, I'll happily accept pull requests. If you can find a bug to squish from the issue log, that would be a great PR to see!

docs/starthere.md

@@ -31,13 +31,14 @@ You should definitely get to know the installation information below to understa
 
 ## Reference
 
+* Again, [POPWorldMedia/POPForums.Sample](https://github.com/POPWorldMedia/POPForums.Sample) is a good starting point when using POP Forums via reference, but the `PopForums.Web` project in the source code works similarly, with project references instead of NuGet references.
 * Reference `PopForums.Mvc` and `PopForums.Sql` from Nuget. If you want to use the scale-out kits (`PopForums.AzureKit` and `PopForums.ElasticKit`), add those as well.
 * Starting with v19, `PopForums.Mvc` includes all of the front-end goodies, the Javascript and CSS, right in the package.
 * You'll need a layout view for the forum to live in.
 * Set up the various options in `Program.cs` as described in its comments and this documentation.
 * `appsettings.json` will have your forum configuration.
 * There is no package for the Azure Functions, because it's currently hard to make them work from a shared library in certain situations. However, you can deploy the project from the main repo with ease given the tooling in VS or Azure DevOps Pipelines. Just be sure to set the right values up in the application configuration in the Azure portal.
-* POP Forums uses ASP.NET Data Protection in multi-node or external login scenarios. Actually, the basic anti-forgery code baked into the framework does as well, so when you deploy, or swap deployment slots in Azure, you need to persist the underlying key somewhere. This is also true if you run multiple nodes (scale out). You can persist the underlying keys in a number of different ways (I prefer Azure Blob Storage). In your `Program.cs`, use `services.AddDataProtection()` and the appropriate extension method. If you don't do this for multi-node, things like social logins and anti-forgery will fail and fill your error logs with stuff about broken things.
+* POP Forums uses ASP.NET Data Protection in multi-node or external login scenarios. Actually, the basic anti-forgery code baked into the framework does as well, so when you deploy, or swap deployment slots in Azure, you need to persist the underlying key somewhere. This is also true if you run multiple nodes (scale out). You can persist the underlying keys in a number of different ways (I prefer Azure Blob Storage). In your `Program.cs`, use `services.AddDataProtection()` and the appropriate extension method. If you don't do this for multi-node, things like social logins and anti-forgery will fail and fill your error logs with stuff about broken things. If you use slots in Azure App Services, you'll also want the Data Protection setup, otherwise the swap will cause everyone to be logged out.
 
 For the bleeding edge, latest build from `main`, the CI build packages can be obtained by a MyGet feed:
 * https://www.myget.org/F/popforums/api/v3/index.json (Nuget package includes the server application and front-end assets)
@@ -46,9 +47,11 @@ For the bleeding edge, latest build from `main`, the CI build packages can be ob
 
 * Download the latest source code from GitHub, or use the production packages as described above. Build it.
 * The project files require an up-to-date version of Visual Studio 2022 or later. It also appears to build in Visual Studio for Mac and Jetbrains' Rider.
-* This project is built on ASP.NET v6. Make sure you have the required SDK installed (v6.0.400).
-* The `PopForums.Web` project is the template to use to include the forum in your app. It references `PopForums.Mvc`, which contains all of the web app-specific code, including script and CSS. `PopForums.Sql` concerns itself only with data, while `PopForums` works entirely with business logic and defines interfaces used in the upstream projects. `PopForums.AzureKit` contains a number of items to facilitate using various Azure services. `PopForums.ElasticKit` contains an ElasticSearch implementation. `PopForums.AzureKit.Functions` is an implementations of functions, used if you're not using in-app context background services (see below).
-* The `main` branch is using Azure Functions by default to run background processes. A recent build of Visual Studio 2022 probably has all of the SDK's but storage emulation is required, so run the [Azurite](https://github.com/azure/azurite) container in Docker (works on Windows and Mac). If not, you can run the background things in-process by uncommenting `services.AddPopForumsBackgroundServices()` in `Program.cs` and commenting out or removing `services.AddPopForumsAzureFunctionsAndQueues()`. This causes all of the background things to run in the context of the web app itself.
+* This project is built on ASP.NET v6. Make sure you have the required SDK installed (v6.0.401).
+* The `PopForums.Web` project is the template to use to include the forum in your app. It references `PopForums.Mvc`, which contains all of the web app-specific code, including script and CSS. `PopForums.Sql` concerns itself only with data, while `PopForums` works entirely with business logic and defines interfaces used in the upstream projects. `PopForums.AzureKit` contains a number of items to facilitate using various Azure services. `PopForums.ElasticKit` contains an ElasticSearch implementation. `PopForums.AzureKit.Functions` is an implementation of functions, used if you're not using in-app context background services (see below).
+* The `main` branch is using Azure Functions by default to run background processes. Run the [Azurite](https://github.com/azure/azurite) container in Docker (works on Windows and Mac). If not, you can run the background things in-process by uncommenting `services.AddPopForumsBackgroundServices()` in `Program.cs` and commenting out or removing `services.AddPopForumsAzureFunctionsAndQueues()`. This causes all of the background things to run in the context of the web app itself.
+
+> Running the background services in the web context can cause some wild variations in CPU and RAM usage on a busy forum, especially in the code associated with updating the search index. If you are running in Azure, using Functions is a much better choice for consistent and predictable app performance.
 
 ## Installation
 
@@ -91,7 +94,7 @@ For the bleeding edge, latest build from `main`, the CI build packages can be ob
 	}
 }
 ```
-* Attempt to run the app locally via Kestrel, and go to the URL /Forums to see an error page. It will fail either because the database isn’t set up, or because it can’t connect to it. The biggest reason for failure is an incorrect connection string. If you change nothing, by default it's looking for a local database on the default SQL Server instance called `popforums19`.
+* Attempt to run the app locally via Kestrel, and go to the URL /Forums to see an error page about not finding the settings table. It will fail either because the database isn’t set up, or because it can’t connect to it. The biggest reason for failure is an incorrect connection string. If you change nothing locally, by default it's looking for a local database on the default SQL Server instance called `popforums19`.
 * If you want to use the setup page (and you should), don’t run the SQL script. Once the POP Forums tables exist in the database, the setup page will tell you that you’re prohibited from going there.
 * Point the browser to /Forums/Setup now, and if your connection string is correct, you should see a page with some of the basic fields to set up.
 * The `PopForums.Mvc` package includes Bootstrap, which is used as the base style for the entire app. To give it your own look, you can add your own CSS to override Bootstrap in your `_Layout.cshtml`, or do your own build of Bootstrap with whatever variables you like. If you prefer your own build, make sure _both_ the Javascript and CSS tags appear _before_ the `RenderSection` in your header, and set the `RenderBootstrap` setting in `appconfig.json` to `false`. Learn more in [customization](customization.md).
@@ -110,6 +113,9 @@ Here’s what each field on the setup page does:
 * **Display name:** How you want your name to appear in the forum.
 * **E-mail:** The e-mail address you’ll use to login with.
 * **Password:** The password you’ll use to login with.
+
+You're almost there!
+
 * If you typed everything you need correctly, you should see a happy result, otherwise you’ll see a stack trace and exception.
 * Restart the app.
 * From here, you can follow the link to the admin home page and add categories and forums. You’ll be logged in as the user you created, and that account will be part of the Admin and Moderator roles.

docs/versionhistory.md

@@ -7,7 +7,7 @@ nav_order: 4
 
 Here's a partial version history that shows how POP Forums has evolved over the years. It's fun to look back at some of the things we now take for granted in a forum app.
 
-## Version v19.0.0 (x/x/22)
+## Version v19.0.0 (10/9/22)
 * Image upload in posts #109
 * Create notification system #265
 * Change PM system to real-time chat #304

src/PopForums.AzureKit.Functions/PopForums.AzureKit.Functions.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 	<PropertyGroup>
 		<Description>PopForums AzureKit Functions</Description>
-		<VersionPrefix>18.0.99</VersionPrefix>
+		<VersionPrefix>19.0.0</VersionPrefix>
 		<Authors>Jeff Putz</Authors>
 		<TargetFramework>net6.0</TargetFramework>
 		<AssemblyName>PopForums.AzureKit.Functions</AssemblyName>

src/PopForums.AzureKit/PopForums.AzureKit.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
 	  <Description>PopForums AzureKit Class Library</Description>
-	  <VersionPrefix>18.0.99</VersionPrefix>
+	  <VersionPrefix>19.0.0</VersionPrefix>
 	  <Authors>Jeff Putz</Authors>
 	  <TargetFramework>net6.0</TargetFramework>
 	  <AssemblyName>PopForums.AzureKit</AssemblyName>

src/PopForums.ElasticKit/PopForums.ElasticKit.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
 	  <Description>PopForums ElasticKit Class Library</Description>
-	  <VersionPrefix>18.0.99</VersionPrefix>
+	  <VersionPrefix>19.0.0</VersionPrefix>
 	  <Authors>Jeff Putz</Authors>
 	  <TargetFramework>net6.0</TargetFramework>
 	  <AssemblyName>PopForums.ElasticKit</AssemblyName>

src/PopForums.Mvc/PopForums.Mvc.csproj

@@ -2,7 +2,7 @@
 
 	<PropertyGroup>
 		<Description>PopForums Mvc Class Library</Description>
-		<VersionPrefix>18.0.99</VersionPrefix>
+		<VersionPrefix>19.0.0</VersionPrefix>
 		<Authors>Jeff Putz</Authors>
 		<TargetFramework>net6.0</TargetFramework>
 		<AssemblyName>PopForums.Mvc</AssemblyName>

src/PopForums.Sql/PopForums.Sql.csproj

@@ -2,7 +2,7 @@
 
 	<PropertyGroup>
 		<Description>PopForums.Data.Sql Class Library</Description>
-		<VersionPrefix>18.0.99</VersionPrefix>
+		<VersionPrefix>19.0.0</VersionPrefix>
 		<Authors>Jeff Putz</Authors>
 		<TargetFramework>net6.0</TargetFramework>
 		<AssemblyName>PopForums.Sql</AssemblyName>

src/PopForums.Test/PopForums.Test.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
 	<PropertyGroup>
-		<VersionPrefix>18.0.99</VersionPrefix>
+		<VersionPrefix>19.0.0</VersionPrefix>
 		<TargetFramework>net6.0</TargetFramework>
 		<AssemblyName>PopForums.Test</AssemblyName>
 		<PackageId>PopForums.Test</PackageId>
@@ -23,10 +23,6 @@
 		<PackageReference Include="xunit" Version="2.4.2" />
 	</ItemGroup>
 
-	<ItemGroup>
-		<Service Include="{82a7f48d-3b50-4b1e-b82e-3ada8210c358}" />
-	</ItemGroup>
-
 	<ItemGroup>
 	  <Folder Include="Messaging\" />
 	</ItemGroup>

src/PopForums.Web/PopForums.Web.csproj

@@ -2,7 +2,7 @@
 
 	<PropertyGroup>
 		<TargetFramework>net6.0</TargetFramework>
-		<VersionPrefix>18.0.99</VersionPrefix>
+		<VersionPrefix>19.0.0</VersionPrefix>
 		<AssemblyName>PopForums.Web</AssemblyName>
 		<PackageId>PopForums.Web</PackageId>
 	</PropertyGroup>

src/PopForums/PopForums.csproj

@@ -2,7 +2,7 @@
 
 	<PropertyGroup>
 		<Description>PopForums Class Library</Description>
-		<VersionPrefix>18.0.99</VersionPrefix>
+		<VersionPrefix>19.0.0</VersionPrefix>
 		<Authors>Jeff Putz</Authors>
 		<TargetFramework>net6.0</TargetFramework>
 		<AssemblyName>PopForums</AssemblyName>