From 1cbfb8c02117c5acea930eb732d5df8f059ae127 Mon Sep 17 00:00:00 2001 From: Natalia Portillo Date: Thu, 19 Aug 2021 13:46:53 +0100 Subject: [PATCH] Updated documentation. --- .github/CODE_OF_CONDUCT.md | 4 +- Aaru.Checksums | 2 +- Aaru.CommonTypes | 2 +- Aaru.Console | 2 +- Aaru.Decoders | 2 +- Aaru.Decryption | 2 +- Aaru/Aaru.csproj | 162 ++++++++++++++++++------------------- CONTRIBUTING.md | 48 ++++++----- GOVERNANCE.md | 31 +++---- MAINTAINERS.md | 2 +- NEEDED.md | 17 +++- NEEDINFO.md | 11 --- README.md | 4 +- 13 files changed, 141 insertions(+), 148 deletions(-) delete mode 100644 NEEDINFO.md diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 918ab68ce..90b1972ed 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -4,7 +4,7 @@ In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, -disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, +disability, ethnicity, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, religion, or sexual identity and orientation. ## Our Standards @@ -54,7 +54,7 @@ repercussions as determined by other members of the project's leadership. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available +This Code of Conduct is adapted from the [Contributor Covenant][https://www.contributor-covenant.org], version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html [homepage]: https://www.contributor-covenant.org diff --git a/Aaru.Checksums b/Aaru.Checksums index da3cbf28f..7fdadfa84 160000 --- a/Aaru.Checksums +++ b/Aaru.Checksums @@ -1 +1 @@ -Subproject commit da3cbf28f464351a0b951bcd14c930952c8ffb21 +Subproject commit 7fdadfa84fd116147cfdd89b6bf6302ebc8ad8a5 diff --git a/Aaru.CommonTypes b/Aaru.CommonTypes index 874a3d4bc..d3451f3e4 160000 --- a/Aaru.CommonTypes +++ b/Aaru.CommonTypes @@ -1 +1 @@ -Subproject commit 874a3d4bcbd6df7d3d60a7cf7deab9f5e903af44 +Subproject commit d3451f3e4d1dc2a0bf33f3bdc4b462893c7091c1 diff --git a/Aaru.Console b/Aaru.Console index dc0e013d8..394c96ed8 160000 --- a/Aaru.Console +++ b/Aaru.Console @@ -1 +1 @@ -Subproject commit dc0e013d8d965752bc585013bdb3191cb05ed92e +Subproject commit 394c96ed824a4187e6ebe3dbcecf986dbc2ec0d8 diff --git a/Aaru.Decoders b/Aaru.Decoders index 8b7e27dca..22f34a17d 160000 --- a/Aaru.Decoders +++ b/Aaru.Decoders @@ -1 +1 @@ -Subproject commit 8b7e27dca58c301b44bc882f91a77a42ef71a13e +Subproject commit 22f34a17d44608bb79c7874a35fed5a20e633924 diff --git a/Aaru.Decryption b/Aaru.Decryption index a19cac220..d6559cb79 160000 --- a/Aaru.Decryption +++ b/Aaru.Decryption @@ -1 +1 @@ -Subproject commit a19cac2209ce7e06ccae6653274d76b8bec9ca6f +Subproject commit d6559cb798d320ba27085fcf0c787591d838a2d0 diff --git a/Aaru/Aaru.csproj b/Aaru/Aaru.csproj index 99ae97d11..96b391b98 100644 --- a/Aaru/Aaru.csproj +++ b/Aaru/Aaru.csproj @@ -50,69 +50,69 @@ false - - - + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - - - + + + - - + + - - + + I @@ -133,28 +133,28 @@ Exception - - - - + + + + _ m_ - + _ m_ - - - - - + + + + + T @@ -162,9 +162,9 @@ - - - + + + @@ -184,10 +184,6 @@ NEEDED.md - - NEEDINFO.md - PreserveNewest - Changelog.md PreserveNewest @@ -198,8 +194,8 @@ {CC48B324-A532-4A45-87A6-6F91F7141E8D} Aaru.Checksums - - + + {F8BDF57B-1571-4CD0-84B3-B422088D359A} Aaru.Helpers @@ -260,26 +256,26 @@ - + - + - - - - - - - - - - - - - - + + + + + + + + + + + + + + -dbg diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ccdc57ad3..38dd2d1eb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ Use your best judgment, and feel free to propose changes to this document in a p [Styleguides](#styleguides) * [Git Commit Messages](#git-commit-messages) -* [Code Styleguide](#code-styleguide) +* [Code Styleguide](#code-style-guide) ## Code of Conduct @@ -75,11 +75,12 @@ Aaru is intentionally very modular. Here's a list of them: functions and commands that are called by the user interface itself. * [Aaru.Decoders](https://github.com/aaru-dps/Aaru.Decoders) - This module contains internal disk, drive and protocol structures as well as code to marshal, decode and print them. +* [Aaru.Decryption](https://github.com/aaru-dps/Aaru.Decryption) - This module contains the media decryption code, like CSS or CPRM. * [Aaru.Devices](https://github.com/aaru-dps/Aaru/tree/master/Aaru.Devices) - This module contains code to talk with - hardware devices in different platforms. Each platform has lowlevel calls in its own folder, and each device protocol - has highlevel calls in its own folder. Device commands are separated by protocol standard, or vendor name. + hardware devices in different platforms. Each platform has low-level calls in its own folder, and each device protocol + has high-level calls in its own folder. Device commands are separated by protocol standard, or vendor name. * [Aaru.Device.Report](https://github.com/aaru-dps/Aaru/tree/master/Aaru.Device.Report) - This is a separate application - in C89 designed to create device reports on enviroments where you can't run .NET or Mono but can run Linux. + in C89 designed to create device reports on environments where you can't run .NET or Mono but can run Linux. * [Aaru.DiscImages](https://github.com/aaru-dps/Aaru/tree/master/Aaru.DiscImages) - This module provides reading capabilities for the disk/disc images, one per file. * [Aaru.DiscImages](https://github.com/aaru-dps/Aaru.Dto) - This module provides common structures between Aaru and @@ -89,8 +90,8 @@ Aaru is intentionally very modular. Here's a list of them: folder should be used. * [Aaru.Filters](https://github.com/aaru-dps/Aaru/tree/master/Aaru.Filters) - A filter is a modification of the data before it can be passed to the disk image module - (compression, fork union, etc), and this module provides support for them. If a image is compressed, say in gzip, or - encoded, say in AppleDouble, a filter is the responsible of decompressing or decoding it on-the-fly. + (compression, fork union, etc.), and this module provides support for them. If an image is compressed, say in gzip, or + encoded, say in AppleDouble, a filter is the responsible for decompressing or decoding it on-the-fly. * [Aaru.Helpers](https://github.com/aaru-dps/Aaru.Helpers) - This module contains a collection of helpers for array manipulation, big-endian marshalling, datetime conversion, hexadecimal printing, string manipulation and byte swapping. @@ -102,21 +103,20 @@ Aaru is intentionally very modular. Here's a list of them: Aaru settings. * [Aaru.Tests](https://github.com/aaru-dps/Aaru/tree/master/Aaru.Tests) - This module contains the unit tests for the rest of the modules. You should add new unit tests here but cannot run all of them because the test images they - require amount to more than 100GiB. -* [Aaru.Tests.Devices](https://github.com/aaru-dps/Aaru/tree/master/Aaru.Tests.Devices) - This module presents a menu - driven interface to send commands to devices, as a way to test the Core module, as those tests cannot be automated. It + require amount to more than 900 GiB. +* [Aaru.Tests.Devices](https://github.com/aaru-dps/Aaru/tree/master/Aaru.Tests.Devices) - This module presents a menu-driven interface to send commands to devices, as a way to test the Core module, as those tests cannot be automated. It can be used to debug drive responses. ## How Can I Contribute? ### Reporting Devices -Aaru tries to be as universal as possible. However some devices do not behave in the expected ways, some media is +Aaru tries to be as universal as possible. However, some devices do not behave in the expected ways, some media is unknown and needs to be known prior to enabling dumping of it, etc. For that reason, Aaru includes the [device-report command](https://github.com/aaru-dps/Aaru/wiki/Reporting-physical-device-capabilities). Using this -command will guide you thru a series of questions about the device, and if it contains removable media, for you to +command will guide you through a series of questions about the device, and if it contains removable media, for you to insert the different media you have, and create a report of its abilities. The report will automatically be sent to our server and saved on your computer. Please note that we do not store any personal information and when possible remove the drive serial numbers from the report. @@ -134,15 +134,15 @@ mag_right:. Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). Fill out -[the required template](.github/ISSUE_TEMPLATE.md), the information it asks for helps us resolve issues faster. +the required template, the information it asks for helps us resolve issues faster. > **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. #### Before Submitting A Bug Report -* **Check the [wiki](https://github.com/aaru-dps/Aaru/wiki)** for a list of common questions and problems. +* **Check the [documentation](https://aaru.app)** for a list of common questions and problems. * **Determine [which module the problem should be reported in](#aaru-and-modules)**. -* **Perform a [cursory search](https://github.com/search?q=+is%3Aissue+user%3Aclaunia)** +* **Perform a [cursory search](https://github.com/search?q=+is%3Aissue)** to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one. @@ -150,8 +150,7 @@ don't need to create one. When you are creating a bug report, please Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined [which module](#aaru-and-modules) your bug is related to, create an issue on that repository and provide the -following information by filling in -[the template](.github/ISSUE_TEMPLATE.md). +following information by filling in the template. Explain the problem and include additional details to help maintainers reproduce the problem: @@ -192,7 +191,7 @@ your suggestion :pencil: and find related suggestions :mag_right:. Before creating enhancement suggestions, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). Fill -in [the template](.github/ISSUE_TEMPLATE.md), including the steps that you imagine you would take if the feature you're +in the template, including the steps that you imagine you would take if the feature you're requesting existed. #### How Do I Submit A (Good) Enhancement Suggestion? @@ -226,16 +225,15 @@ If you want to read about using Aaru, the [wiki](https://github.com/aaru-dps/Aar Do not modify the interfaces. If you need or want to, comment in an issue how and why you want to change it and we'll discuss it. Same applies for creating new interfaces. -Aaru uses C# 7 language features (inline declaration, Tuples, etc.) so it can only be compiled -with [VisualStudio](http://www.visualstudio.com) 2017 or higher, [Xamarin Studio](https://www.xamarin.com/download) -7 or higher, [MonoDevelop](http://www.monodevelop.com) 7 or higher, -or [JetBrains Rider](https://www.jetbrains.com/rider/) 2017.2 or higher. +Aaru uses C# 8 language features (inline declaration, Tuples, etc.) so it can only be compiled +with [VisualStudio](http://www.visualstudio.com) 2019 or higher, [Visual Studio for Mac](https://www.xamarin.com/download) +2019 or higher, or [JetBrains Rider](https://www.jetbrains.com/rider/) 2019.1 or higher. ### Pull Requests * Fill in [the required template](.github/PULL_REQUEST_TEMPLATE.md) * Do not include issue numbers in the PR title -* Follow the [code styleguide](#code-styleguide). +* Follow the [code styleguide](#code-style-guide). * Include test files as applicable, that do not have software under copyright inside them, if possible. * Document new code based using XML documentation wherever possible. * DO NOT end files with a newline. @@ -265,7 +263,7 @@ for them. * Use the present tense ("Add feature" not "Added feature") * Use the imperative mood ("Move cursor to..." not "Moves cursor to...") -* Limit the first line to 72 characters or less +* Limit the first line to 72 characters or fewer * Reference issues and pull requests liberally after the first line ### Code Style Guide @@ -282,7 +280,7 @@ for them. - If you will only store variables, use a struct. If you need it to be nullable, use a nullable struct if applicable. - Indent statements and cases. - Indent using 4 spaces (soft tab). -- Instace and static fields should be lowerCamelCase. +- Instance and static fields should be lowerCamelCase. - Public fields should be UpperCamelCase. - Separate attributes. - Use 120 columns margins. @@ -291,7 +289,7 @@ for them. - Use implicit modifiers. - Use inline variable declaration. - Use struct implicit constructor. -- Use UNIX (`\n`) endline character. +- Use UNIX (`\n`) end line character. > Note: There is an included editorconfig file that sets the appropriate code style. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 435ecb1db..0e14e4277 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -12,23 +12,24 @@ The community is governed by this document with the goal of defining how communi The following code repositories are governed by Aaru community and maintained under the `aaru-dps` organization. -* **[Aaru](https://github.com/aaru-dps/aaru):** Main Aaru codebase. -* **[Aaru.Documentation](https://github.com/aaru-dps/Aaru.Documentation):** Official documentation. -* **[Aaru.Decryption](https://github.com/aaru-dps/Aaru.Decryption):** Library for the decryption of media. -* **[Aaru.CommonTypes](https://github.com/aaru-dps/Aaru.CommonTypes):** Common types needed by the different Aaru modules. -* **[Aaru.Decoders](https://github.com/aaru-dps/Aaru.Decoders):** Library for the decoding of structures from media and drives. -* **[Aaru.Server](https://github.com/aaru-dps/Aaru.Server):** https://aaru.app server codebase. -* **[fstester](https://github.com/aaru-dps/fstester):** Toolkit for the generation of test filesystems for later reverse engineer. -* **[aaruremote](https://github.com/aaru-dps/aaruremote):** Small application allowing to send Aaru commands to a different computer. -* **[Aaru.Dto](https://github.com/aaru-dps/Aaru.Dto):** DTOs for interchange between client and server portions of Aaru. -* **[Aaru.Console](https://github.com/aaru-dps/Aaru.Console):** Text console handler. -* **[Aaru.Helpers](https://github.com/aaru-dps/Aaru.Helpers):** Helper functions. -* **[Aaru.Checksums](https://github.com/aaru-dps/Aaru.Checksums):** Library that implements the hashing functionality. * **[010templates](https://github.com/aaru-dps/010templates):** Templates for [010editor](https://www.sweetscape.com/010editor). -* **[libaaruformat](https://github.com/aaru-dps/libaaruformat):** Main implementation of Aaru Media Image Format. +* **[Aaru.Checksums](https://github.com/aaru-dps/Aaru.Checksums):** Library that implements the hashing functionality. +* **[Aaru.CommonTypes](https://github.com/aaru-dps/Aaru.CommonTypes):** Common types needed by the different Aaru modules. +* **[Aaru.Console](https://github.com/aaru-dps/Aaru.Console):** Text console handler. +* **[Aaru.Decoders](https://github.com/aaru-dps/Aaru.Decoders):** Library for the decoding of structures from media and drives. +* **[Aaru.Decryption](https://github.com/aaru-dps/Aaru.Decryption):** Library for the decryption of media. +* **[Aaru.Documentation](https://github.com/aaru-dps/Aaru.Documentation):** Official documentation. +* **[Aaru.Dreamcast](https://github.com/aaru-dps/Aaru.Dreamcast):** Tool for dumping GD-ROM using a real Dreamcast. +* **[Aaru.Dto](https://github.com/aaru-dps/Aaru.Dto):** DTOs for interchange between client and server portions of Aaru. +* **[Aaru.Helpers](https://github.com/aaru-dps/Aaru.Helpers):** Helper functions. +* **[Aaru](https://github.com/aaru-dps/aaru):** Main Aaru codebase. +* **[aaruremote](https://github.com/aaru-dps/aaruremote):** Small application allowing to send Aaru commands to a different computer. +* **[Aaru.Server](https://github.com/aaru-dps/Aaru.Server):** https://aaru.app server codebase. * **[Aaru.VideoNow](https://github.com/aaru-dps/Aaru.VideoNow):** VideoNow decoding and converting tool. * **[archaaru](https://github.com/aaru-dps/archaaru):** Scripts for the generation of Arch Linux Rescue CD including Aaru Data Preservation Suite. -* **[Aaru.Dreamcast](https://github.com/aaru-dps/Aaru.Dreamcast):** Tool for dumping GD-ROM using a real Dreamcast. +* **[fstester](https://github.com/aaru-dps/fstester):** Toolkit for the generation of test filesystems for later reverse engineer. +* **[libaaruformat](https://github.com/aaru-dps/libaaruformat):** Main implementation of Aaru Media Image Format. +* **[RedBookPlayer](https://github.com/aaru-dps/RedBookPlayer):** Application to play Red Book audio from media dumps. ## Community Roles @@ -48,7 +49,7 @@ New technical committee members must be nominated by an existing member and must ### Supermajority A supermajority is defined as two-thirds of members in the group. -A supermajority of [Maintainers](#maintainers) is required for certain decisions as outlined above. A supermajority vote is equivalent to the number of votes in favor being at least twice the number of votes against. For example, if you have 5 maintainers, a supermajority vote is 4 votes. Voting on decisions can happen on the mailing list, GitHub, Discord, email, or via a voting service, when appropriate. Maintainers can either vote "agree, yes, +1", "disagree, no, -1", or "abstain". A vote passes when supermajority is met. An abstain vote equals not voting at all. +A supermajority of [Maintainers](MAINTAINERS.md) is required for certain decisions as outlined above. A supermajority vote is equivalent to the number of votes in favor being at least twice the number of votes against. For example, if you have 5 maintainers, a supermajority vote is 4 votes. Voting on decisions can happen on the mailing list, GitHub, Discord, email, or via a voting service, when appropriate. Maintainers can either vote "agree, yes, +1", "disagree, no, -1", or "abstain". A vote passes when supermajority is met. An abstain vote equals not voting at all. ### Decision Making diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 4e147be43..409d53344 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -9,6 +9,7 @@ | Natalia Portillo | [claunia](https://github.com/claunia) | [Aaru](https://aaru.app) | | Michael Drüing | [darkstar](https://github.com/darkstar) | [Aaru](https://aaru.app) | | Rebecca Wallander | [FakeShemp](https://github.com/FakeShemp) | [Aaru](https://aaru.app) | +| Matt Nadareski | [mnadareski](https://github.com/mnadareski) | [Aaru](https://aaru.app) | ## Technical committee @@ -25,4 +26,3 @@ | Development | Michael Drüing | [darkstar](https://github.com/darkstar) | [Aaru](https://aaru.app) | | Development | Rebecca Wallander | [FakeShemp](https://github.com/FakeShemp) | [Aaru](https://aaru.app) | | QA | Silas Laspada | [SilasLaspada](https://github.com/SilasLaspada) | [Aaru](https://aaru.app) | -| MPF (UI) | Matt Nadareski | [mnadareski](https://github.com/mnadareski) | SabreTools | diff --git a/NEEDED.md b/NEEDED.md index 89e0ac3de..26c1e0961 100644 --- a/NEEDED.md +++ b/NEEDED.md @@ -12,12 +12,10 @@ special workarounds. If a drive is listed here, but the media it uses is not lis Drives are preferred in ATA/ATAPI, SCSI, USB or FireWire buses. Parallel port drives require a larger amount of work, and there is no guarantee it can work, at all, with other drives. If in doubt, please contact us. -- 5.25" magneto-optical (preferibly the 9.6Gb supporting one) - 8" shugart floppy drive (preferibly the 240VAC one) - ADR tape drive - AIT tape drive - Apple FileWare "twiggy" -- Caleb UHD144 - Castlewood Orb 5.7 - DLT tape drive - DiscFerret @@ -50,7 +48,6 @@ hardware. - ADR tapes - AIT tapes - Apple FileWare "twiggy" floppies -- Caleb UHD144 floppy - Castlewood Orb 5.7 - DLTtape, DLTtapeII, DLTtapeIII - Rewritable HD-DVD @@ -138,4 +135,16 @@ dumping of such characteristics. Usually those are copy protections. - I Am Alive - ObsCure II - Shift 2 Unleashed - - Warfare \ No newline at end of file + - Warfare + +Information and test data +========================= + +This is a list of information I need, including test disk images. + +- DiscFerret stream images +- Information about the KenCode compression algorithm, or an implementation in C or Pascal +- Information about the structure and compression algorithm for XPACK disk images, or an implementation in C +- KryoFlux stream images +- NetWare 286 license and installation media for adding support to its filesystem +- NetWare 386 license and installation media for adding support to its filesystem \ No newline at end of file diff --git a/NEEDINFO.md b/NEEDINFO.md deleted file mode 100644 index 7a1b6804c..000000000 --- a/NEEDINFO.md +++ /dev/null @@ -1,11 +0,0 @@ -Information and test data -========================= - -This is a list of information I need, including test disk images. - -- DiscFerret stream images -- Information about the KenCode compression algorithm, or an implementation in C or Pascal -- Information about the structure and compression algorithm for XPACK disk images, or an implementation in C -- KryoFlux stream images -- NetWare 286 license and installation media for adding support to its filesystem -- NetWare 386 license and installation media for adding support to its filesystem \ No newline at end of file diff --git a/README.md b/README.md index 4c45128b6..79bb15d76 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Copyright © 2011-2021 Natalia Portillo [![Build status](https://ci.appveyor.com/api/projects/status/vim4c8h028pn5oys?svg=true)](https://ci.appveyor.com/project/claunia/aaru) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fclaunia%2FDiscImageChef.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fclaunia%2FDiscImageChef?ref=badge_shield) -You can see statistics and device reports [here](https://www.aaru.app/Stats) +You can see user documentation [here](https://www.aaru.app) Aaru is a fully featured media dump management solution. You usually know media dumps as disc images, disk images, tape images, etc. @@ -38,7 +38,7 @@ aaru.exe And read help. -Or read the [documentation](https://github.com/aaru-dps/Aaru.Documentation/blob/master/5.0/README.md). +Or read the [documentation](https://www.aaru.app). Features ========