From 58d48b24196ac09895c8d0b23718d6b78c0708e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexandre=20Rab=C3=A9rin?= Date: Mon, 28 Oct 2019 14:04:49 +0100 Subject: [PATCH] Write release notes for the first QuikGraph package. Add some historical background. --- README.md | 6 +-- RELEASE_NOTES.md | 39 ++++++++--------- docs/docfx.json | 2 + docs/documentation/history.md | 78 ++++++++++++++++++++++++++++++++++ docs/documentation/toc.yml | 2 + docs/index.md | 6 +-- docs/toc.yml | 2 + releaseDoc.ps1 | 28 ++++++------ src/QuikGraph/QuikGraph.csproj | 17 +++++++- 9 files changed, 138 insertions(+), 42 deletions(-) create mode 100644 docs/documentation/history.md create mode 100644 docs/documentation/toc.yml diff --git a/README.md b/README.md index ce44ca748..701d1513b 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ QuikGraph comes with algorithms such as depth first search, breath first search, It was then updated to become YC.QuickGraph. -This version of QuickGraph, renamed QuikGraph, is a fork of YC.QuickGraph, and I tried to clean the Core of the library to provide it as a clean NuGet package using modern C# development. +**This version** of QuickGraph, renamed **QuikGraph**, is a fork of YC.QuickGraph, and I tried to clean the Core of the library to provide it as a clean NuGet package using modern C# development (.NET Core). The plan would be to fully clean the original library and all its non Core parts and unit test it more. @@ -41,14 +41,14 @@ The plan would be to fully clean the original library and all its non Core parts ### Notes -It uses NUnit3 for unit testing (not published). +The library get rid of PEX that was previously used for unit tests and now uses NUnit3 (not published). I would be very pleased to receive pull requests to further **test** or **improve** the library. ### Where to go next? * [Documentation](https://kernelith.github.io/QuikGraph/) -* [External Information](https://quickgraph.codeplex.com/documentation) +* [External Information](https://quickgraph.codeplex.com/documentation) (The website was closed) ### Maintainer(s) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index c7f91d780..1f73e1d57 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,26 +1,23 @@ -#### 3.7.5-deta January 17 2019 -* Code cleanup -* Minor fixes -* DotParser is turned off +# Release notes -#### 3.7.4 August 27 2018 -* More algorithms (TransitiveClosure, YenShortestPaths, etc.) -* Code cleanup -* Minor fixes +## What's new in 1.0.0 December 10 2019 -#### 3.7.3 August 23 2016 -* Minor fix in packet dependences specification +This release is was based on YC.QuikGraph 3.7.5-deta with a lot of updates. -#### 3.7.2 August 18 2016 -* Update DotParser to latest version (1.0.6) +### General: +* Fully clean the library code. +* Extend support of the library to .NET Framework 3.5+. +* Extend support of the library to .NET Core 1.0+. +* Various fixes for graphs and algorithms implementations. +* Uniformize APIs and behaviors of graphs and algorithms implementations. -#### 3.7.1 July 12 2016 -* Minor fixes -* New graph algorithms for graph partition, coloring, searching paths, etc -* Graphs now can be loaded from DOT -* Drop Portable Class Library support +Note: Only keep the Core of QuikGraph for this package (feature split). -#### 3.7.0 July 12 2016 -* New graph algorithms for graph partition, coloring, searching paths, etc -* Graphs now can be loaded from DOT -* Drop Portable Class Library support \ No newline at end of file +### API Breaks +* Some public API breaks (but should remain simple to do a migration). +* Some edges structures are removed, the classes implementations are preferred due to C# limitations. +* Some algorithms are not usable for now (wrong implementations) and are removed from public API. + +### Misc: +* Generate a documentation for the library via DocFX. +* Use JetBrains annotations all over the library as much as possible. \ No newline at end of file diff --git a/docs/docfx.json b/docs/docfx.json index 57c73722d..2eeb98e35 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -32,6 +32,8 @@ }, { "files": [ + "documentation/**.md", + "documentation/**/toc.yml", "toc.yml", "*.md" ] diff --git a/docs/documentation/history.md b/docs/documentation/history.md new file mode 100644 index 000000000..096f3e315 --- /dev/null +++ b/docs/documentation/history.md @@ -0,0 +1,78 @@ +# Library history + +Below is some summarized information about the history of this library in order to have a better idea of where it comes from. + +## QuickGraph + +### General information + +This is the original library supporting .NET Framework 4.0, Silverlight 4.0, Windows Phone 7, Windows 8 Metro Apps, XBox 360. + +QuikGraph was originally created by Jonathan "Peli" de Halleux in 2003. + +Intially the library was providing generic directed/undirected graph datastructures and algorithms for .NET. +QuickGraph was coming with algorithms such as depth first seach, breath first search, A* search, shortest path, k-shortest path, maximum flow, minimum spanning tree, least common ancestors, etc... +QuickGraph was supporting [MSAGL](https://www.microsoft.com/en-us/research/project/microsoft-automatic-graph-layout), [GLEE](https://en.wikipedia.org/wiki/Microsoft_Automatic_Graph_Layout), and [Graphviz](https://www.graphviz.org) to render the graphs, serialization to [GraphML](http://graphml.graphdrawing.org), etc... + +The library was also using [Code Contracts](https://www.microsoft.com/en-us/research/project/code-contracts/?from=http%3A%2F%2Fresearch.microsoft.com%2Fcontracts). + +Note that the library was widely used such as in those projects: +- [Reflector.Graph Addin](https://archive.codeplex.com/?p=reflectoraddins) +- [Graph#, layout algorithms](https://archive.codeplex.com/?p=graphsharp) +- [Jolt.Net, a backing store for a generic finite state machine implementation](https://archive.codeplex.com/?p=jolt) +- [JSL StyleCop, Custom rules for Microsoft's StyleCop utility](https://archive.codeplex.com/?p=jslstylecop) +- [NDepend, codebase macro analysis](https://www.ndepend.com) +- [Dependency Viewer](https://archive.codeplex.com/?p=dependencyvisualizer) + +### Versions + +- QuickGraph 3.6. Portable Class Library support. +- QuickGraph 3.3.51106.0 available on nuget, no more support for .NET 2.0. +- QuickGraph 3.3 (updated) added Code Contracts reference assemblies +- QuickGraph 3.3 adds new graph data structures based on delegates +- QuickGraph 3.2 (bis) supporting Silveright +- QuickGraph 3.2 started using Code Contracts. +- QuickGraph 3.1 brings a Fibonacci Heap and support for 2.0 is back. +- QuickGraph 3.0 takes advantage of extension methods to simplify tasks. +- QuickGraph 2.0 introduced support for generic graph data structures +- The original QuickGraph for .net 1.0 was posted on CodeProject in 8 Dec 2003. It was time to do a refresh and make the graph generic. + +The design of QuickGraph is inspired from the [Boost Graph Library](https://www.boost.org/doc/libs/1_68_0/libs/graph/doc/index.html). + +## YC.QuickGraph + +### General information + +The YC.QuickGraph is a library that took sources of the original QuickGraph and put them on NuGet as package. + +The goal was to continue the development (as described [there](https://github.com/YaccConstructor/QuickGraph/issues/173)). + +It kept the majority of legacy code from QuickGraph and was applied some fixes. + +### Versions + +- YC.QuickGraph 3.7.5-deta Fixes, clean, no more DotParser. +- YC.QuickGraph 3.7.4 Some new algorithms, fixes and clean. +- YC.QuickGraph 3.7.3 Fixes. +- YC.QuickGraph 3.7.2 N/A. +- YC.QuickGraph 3.7.1 Some new algorithms, add DotParser and remove portable class library support. + +## QuikGraph + +### General information + +QuikGraph library was built based on YC.QuickGraph (fork) that is itself based on the original QuickGraph. + +The goal of this library was to clean and provide a more stable version of QuickGraph, which also follows new C# development standards. + +As a consequence a massive clean and unit testing was added to the library. + +Note that for now the cleaned library only concern the QuickGraph **core**, not its legacy adapters. This in order to better split features provided by NuGet packages. + +This version of QuickGraph also get rid of: +- Code Contracts in favor of JetBrains contract annotations and standard asserts. +- PEX in favor of NUnit3 for unit testing. + +### Versions + +- QuikGraph 1.0.0 See [release notes](https://www.nuget.org/packages/QuikGraph/1.0.0). \ No newline at end of file diff --git a/docs/documentation/toc.yml b/docs/documentation/toc.yml new file mode 100644 index 000000000..b6abd3dc0 --- /dev/null +++ b/docs/documentation/toc.yml @@ -0,0 +1,2 @@ +- name: History + href: history.md \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 2d02a73bb..1328029b3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ ## Introduction -**QuikGraph** provides generic directed/undirected graph data structures and algorithms for .NET. +QuikGraph provides generic directed/undirected graph data structures and algorithms for .NET. QuikGraph comes with algorithms such as depth first search, breath first search, A* search, shortest path, k-shortest path, maximum flow, minimum spanning tree, etc. @@ -20,7 +20,7 @@ QuikGraph comes with algorithms such as depth first search, breath first search, It was then updated to become YC.QuickGraph. -This version of QuickGraph, renamed QuikGraph, is a fork of YC.QuickGraph, and I tried to clean the Core or the library to provide it as a clean NuGet package using modern C# development. +**This version** of QuickGraph, renamed **QuikGraph**, is a fork of YC.QuickGraph, and I tried to clean the Core of the library to provide it as a clean NuGet package using modern C# development (.NET Core). The plan would be to fully clean the original library and all its non Core parts and unit test it more. @@ -36,6 +36,6 @@ You can find library sources on [GitHub](https://github.com/KeRNeLith/QuikGraph) QuikGraph is available on [NuGet](https://www.nuget.org/packages/QuikGraph) - PM> Install-Package QuikGraph + PM> Install-Package QuikGraph \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml index a4d4abfe0..578e970d8 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,3 +1,5 @@ +- name: Documentation + href: documentation/ - name: API Reference href: api/ homepage: api/index.md diff --git a/releaseDoc.ps1 b/releaseDoc.ps1 index 9d517d6e7..9ce20bde3 100644 --- a/releaseDoc.ps1 +++ b/releaseDoc.ps1 @@ -50,14 +50,14 @@ param( # Only master Release if ($env:Configuration -ne "Release") { - "Documentation update ignored: Not Release build."; - Return; + "Documentation update ignored: Not Release build."; + Return; } if ($env:APPVEYOR_REPO_BRANCH -ne "master") { - "Documentation update ignored: Not master branch."; - Return; + "Documentation update ignored: Not master branch."; + Return; } # Chocolatey DocFX @@ -84,8 +84,8 @@ $TEMP_REPO_DIR="$pwd/../QuikGraph-gh-pages" if (Test-Path $TEMP_REPO_DIR) { - "Removing temporary documentation directory $TEMP_REPO_DIR..." - rm -recurse $TEMP_REPO_DIR + "Removing temporary documentation directory $TEMP_REPO_DIR..." + rm -recurse $TEMP_REPO_DIR } mkdir $TEMP_REPO_DIR @@ -106,15 +106,15 @@ Invoke-Git "add -A ." "Checking if there are changes in the documentation..." if (-not [string]::IsNullOrEmpty($(git status --porcelain))) { - "Pushing the new documentation to the remote gh-pages branch..." - - git commit -m "Update generated documentation." - # -q is to avoid git to output thing to stderr for no reason - git push -q origin gh-pages - - "Documentation updated in remote gh-pages branch." + "Pushing the new documentation to the remote gh-pages branch..." + + git commit -m "Update generated documentation." + # -q is to avoid git to output thing to stderr for no reason + git push -q origin gh-pages + + "Documentation updated in remote gh-pages branch." } else { - "Documentation update ignored: No relevant changes in the documentation." + "Documentation update ignored: No relevant changes in the documentation." } \ No newline at end of file diff --git a/src/QuikGraph/QuikGraph.csproj b/src/QuikGraph/QuikGraph.csproj index 8f2bca942..19ca604f8 100644 --- a/src/QuikGraph/QuikGraph.csproj +++ b/src/QuikGraph/QuikGraph.csproj @@ -34,7 +34,22 @@ Supported platforms: true QuikGraph - ➟ Release 1.0.0 + ➟ Release 1.0.0 +This package is a version of the original QuickGraph renamed QuikGraph and ported to .NET Core. + +It does not include every sub modules of the original library such as F# stuff, adapters, etc. +This build is only the Core of QuikGraph taking advantage of .NET Core. + +This package should be seen as an alternative one to the old frozen QuickGraph from CodePlex but with fixes. + +The library has been cleaned a lot (code smells, etc) and is much more unit tested. +Some implementations have been fixed (Yen algorithm, etc). +Note that some public API of the original QuickGraph may have slighly changed but the migration should remain easy. +This goal of this release was also to uniformize the more it is possible the behavior of various graph structures and algorithms. + +It also has been fully documented and most of the library is using JetBrains annotations. + +Finally the targets supported by the library has been extended to .NET Framework 3.5+ and also works for .NET Core 1.0+. QuickGraph QuikGraph Graph Structure Algorithm C# .NET true