diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..a7edb76a1 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,73 @@ +# Contributor Covenant Code of Conduct for DiscImageChef + +## Our Pledge + +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, nationality, personal appearance, race, +religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at [claunia@claunia.com](mailto:claunia@claunia.com). All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent 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 at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 000000000..a6b1d04b1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,49 @@ +### Prerequisites + +* [ ] Are you running the latest version? +* [ ] Can you reproduce the problem in the debug version? + +### Check and fill as appropiate: +* [ ] I was running DiscImageChef under Windows [version here]... +* [ ] I was running DiscImageChef under Linux [version here]... +* [ ] I was running DiscImageChef under FreeBSD [version here]... +* [ ] I was running DiscImageChef under macOS [version here]... +* [ ] ...using .NET Framework [version here]... +* [ ] ...using .NET Core [version here]... +* [ ] ...using Mono [version here]... +* [ ] ...in 32-bit +* [ ] ...in 64-bit + +### Description + +[Description of the bug or feature] + +### Exact command line used: + +`DiscImageChef [command] [parameters]` + +### Expected behavior: +[What you expected to happen] + +### Actual behavior: +[What actually happened] + +### If command was expected to work with a device fill this: + +* **Manufacturer**: +* **Model**: +* **Bus**: + * [ ] Parallel ATA + * [ ] Serial ATA + * [ ] SCSI (any) + * [ ] ATAPI (mark above if parallel or serial) + * [ ] USB + * [ ] FireWire + * [ ] PCMCIA + * [ ] SecureDigital + * [ ] MultiMediaCard + +### Output of command execution with debug output enabled +``` +Paste here the whole output of the executed command when you append '-d' to your command line parameters +``` \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..8887e634c --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,14 @@ +## Types of changes + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] New filesystem, test images in [url] +- [ ] New disc image, test images in [url] +- [ ] New partition scheme, test images in [url] +- [ ] Breaking change (fix or feature that would cause existing functionality to change) +- [ ] I have read the **CONTRIBUTING** document. +- [ ] My code follows the code style of this project. +- [ ] My change requires a change to the documentation. +- [ ] I have updated the documentation accordingly. +- [ ] I have added tests to cover my changes. +- [ ] All new and existing tests passed. \ No newline at end of file diff --git a/CODING.md b/CODING.md deleted file mode 100644 index 5f62d967c..000000000 --- a/CODING.md +++ /dev/null @@ -1,123 +0,0 @@ -Coding -====== - -Contributing with code to DiscImageChef has three very simple rules: - -- Use same style as currently used. In a nutshell: - - Tabs instead of spaces - - Brackets in separate lines - - UNIX line endings - - Do not separate parenthesis, - - Indent every code block (for, foreach, while, if, switch, case) -- 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. -- Everything has a place, a module and an interface. Following is the list of interfaces. -- DiscImageChef uses C# 7 language features (inline declaration, Tuples, etc.) so it can only be compiled with VisualStudio 2017 or higher, Xamarin Studio 7 or higher, or MonoDevelop 7 or higher. - - -[Claunia.RsrcFork](https://github.com/claunia/Claunia.RsrcFork) ---------------------------------------------------------------- -- License: MIT - -This library includes code for handling Mac OS resource forks, and decoding them, so any code relating to Mac OS resource forks should be added here. - -[Claunia.Encoding](https://github.com/claunia/Claunia.Encoding) ---------------------------------------------------------------- -- License: MIT - -This library includes code for converting codepages not supported by .NET, like those used by ancient operating systems, to/from UTF-8. - -[plist-cil](https://github.com/claunia/plist-cil) -------------------------------------------------- -- License: MIT - -This library includes code for handling Apple property lists. - -[SharpCompress](https://github.com/adamhathcock/sharpcompress) --------------------------------------------------------------- -- License: MIT - -This library includes code for handling compression algorithms and compressed archives. -Any need you have of compression or decompression should be handled with this library, and any new algorithm should be added here. - -[DiscImageChef](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef) ------------------------------------------------------------------------------------ -- License: GPL - -This module contains the command line interface and core code. -In the future the core code will be separated from the CLI and a GUI will be added. - -[DiscImageChef.Checksums](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Checksums) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -This module contains the checksum, hashing and error correction algorithms. - -[DiscImageChef.Checksums](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.CommonTypes) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -This module contains structs and enumerations needed by more than one of the other modules. - -[DiscImageChef.Decoders](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Decoders) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -This module contains internal disk, drive and protocol structures as well as code to marshal, decode and print them. - -[DiscImageChef.Devices](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Devices) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -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. - -[DiscImageChef.DiscImages](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.DiscImages) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -This module provides reading capabilities for the disk/disc images, one per file. - -[DiscImageChef.Filesystems](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Filesystems) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -This module provides the filesystem support. If only identification is implemented a single file should be used. For full read-only support, a folder should be used. - -[DiscImageChef.Filters](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Filters) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -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. - -[DiscImageChef.Helpers](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Helpers) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -This module contains a collection of helpers for array manipulation, big-endian marshalling, datetime conversion, hexadecimal printing, string manipulation and byte swapping. - -[DiscImageChef.Interop](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Interop) -------------------------------------------------------------------------------------------------------- -- License: MIT - -This module contains calls to the underlying operating system. Currently only OS detection is needed. - -[DiscImageChef.Metadata](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Metadata) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -This module contains handling of CICM XML metadata, media types and dimensions. - -[DiscImageChef.Partitions](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Partitions) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -This module contains code for reading partition schemes. - -[DiscImageChef.Settings](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Settings) -------------------------------------------------------------------------------------------------------- -- License: LGPL - -This module contains code for handling DiscImageChef settings. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52bab5ba6..86a798b8f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,328 @@ -So, if you're reading this file it meants you are interested on helping DiscImageChef somehow. -There are basically four ways to help. Click on each one for details. +# Contributing to DiscImageChef -- [Testing and bug reporting](TESTING.md) -- [Information and test data](NEEDINFO.md) -- [Coding](CODING.md) -- [Hardware donations](DONATING.md) \ No newline at end of file +:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: + +The following is a set of guidelines for contributing to DiscImageChef and its modules. +These are mostly guidelines, not rules. Use your best judgment, and feel free to propose +changes to this document in a pull request. + +#### Table Of Contents + +[Code of Conduct](#code-of-conduct) + +[I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question) + +[What should I know before I get started?](#what-should-i-know-before-i-get-started) + * [DiscImageChef and modules](#discimagechef-and-modules) + +[How Can I Contribute?](#how-can-i-contribute) + * [Reporting Devices](#reporting-devices) + * [Reporting Bugs](#reporting-bugs) + * [Suggesting Enhancements](#suggesting-enhancements) + * [Your First Code Contribution](#your-first-code-contribution) + * [Pull Requests](#pull-requests) + * [Patronizing us](#patronizing) + * [Donating hardware to test](#donating) + * [Providing information](#needed-information) + +[Styleguides](#styleguides) + * [Git Commit Messages](#git-commit-messages) + * [Code Styleguide](#code-styleguide) + +## Code of Conduct + +This project and everyone participating in it is governed by the +[DiscImageChef Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected +to uphold this code. Please report unacceptable behavior to [claunia@claunia.com](mailto:claunia@claunia.com). + +## I don't want to read this whole thing I just have a question!!! + +> **Note:** Please don't file an issue to ask a question. You'll get faster results by +using the resources below. + +You can join our IRC channel on char.freenode.net at channel #DiscImageChef + +## What should I know before I get started? + +### DiscImageChef and modules + +DiscImageChef is a large open source project — it's made up of 18 modules. When you initially consider contributing to DiscImageChef, you might be unsure about which of those modules implements the functionality you want to change or report a bug for. This section should help you with that. + +DiscImageChef is intentionally very modular. Here's a list of them: + +* [Claunia.RsrcFork](https://github.com/claunia/Claunia.RsrcFork) - +This library includes code for handling Mac OS resource forks, and decoding them, so any +code related to Mac OS resource forks should be added here. +* [Claunia.Encoding](https://github.com/claunia/Claunia.Encoding) - +This library includes code for converting codepages not supported by .NET, like those used +by ancient operating systems, to/from UTF-8. +* [plist-cil](https://github.com/claunia/plist-cil) - +This library includes code for handling Apple property lists. +* [SharpCompress](https://github.com/adamhathcock/sharpcompress) - +This library includes code for handling compression algorithms and compressed archives. Any +need you have of compression or decompression should be handled with this library, and any new algorithm should be added here. +* [DiscImageChef](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef) - +This module contains the command line interface. In the future a GUI will be added. +* [DiscImageChef.Checksums](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Checksums) - +This module contains the checksum, hashing and error correction algorithms. +* [DiscImageChef.CommonTypes](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.CommonTypes) - +This module contains structs and enumerations needed by more than one of the other modules. +* [DiscImageChef.Console](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Console) - +This module abstracts consoles used by other modules to output information, so they can be +redirected to a CLI or to a GUI output. +* [DiscImageChef.Core](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Core) - +This module contains the implementation of the functions and commands that are called by the +user interface itself. +* [DiscImageChef.Decoders](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Decoders) - +This module contains internal disk, drive and protocol structures as well as code to marshal, +decode and print them. +* [DiscImageChef.Devices](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.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. +* [DiscImageChef.Device.Report](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.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. +* [DiscImageChef.DiscImages](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.DiscImages) - +This module provides reading capabilities for the disk/disc images, one per file. +* [DiscImageChef.Filesystems](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Filesystems) - +This module provides the filesystem support. If only identification is implemented a single +file should be used. For full read-only support, a folder should be used. +* [DiscImageChef.Filters](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.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. +* [DiscImageChef.Helpers](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Helpers) - +This module contains a collection of helpers for array manipulation, big-endian marshalling, +datetime conversion, hexadecimal printing, string manipulation and byte swapping. +* [DiscImageChef.Interop](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Interop) - +This module contains calls to the underlying operating system. Currently only OS detection is +needed. +* [DiscImageChef.Metadata](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Metadata) - +This module contains handling of CICM XML metadata, media types and dimensions. +* [DiscImageChef.Partitions](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Partitions) - +This module contains code for reading partition schemes. +* [DiscImageChef.Server](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Server) - +This module contains the server-side code that's running at http://discimagechef.claunia.com +* [DiscImageChef.Settings](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Settings) - +This module contains code for handling DiscImageChef settings. +* [DiscImageChef.Tests](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.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. +* [DiscImageChef.Tests.Devices](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.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 + +DiscImageChef 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, DiscImageChef includes the [device-report command](https://github.com/claunia/DiscImageChef/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 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. + +If you have a drive attached to a computer that you cannot run the full DiscImageChef on it +but can compile a C89 application, you can use [DiscImageChef.Device.Report](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Device.Report). +In this case the report will only be created locally and you should attach it to a bug report. + +### Reporting Bugs + +This section guides you through submitting a bug report for DiscImageChef. Following these guidelines +helps maintainers and the community understand your report :pencil:, reproduce the +behavior :computer: :computer:, and find related reports :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](ISSUE_TEMPLATE.md), 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/claunia/DiscImageChef/wiki)** for a list of common +questions and problems. +* **Determine [which module the problem should be reported in](#discimagechef-and-modules)**. +* **Perform a [cursory search](https://github.com/search?q=+is%3Aissue+user%3Aclaunia)** +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. + +#### How Do I Submit A (Good) Bug Report? + +Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). After +you've determined [which module](#discimagechef-and-modules) your bug is related to, +create an issue on that repository and provide the following information by filling in +[the template](ISSUE_TEMPLATE.md). + +Explain the problem and include additional details to help maintainers reproduce the problem: + +* **Use a clear and descriptive title** for the issue to identify the problem. +* **Describe the exact steps which reproduce the problem** in as many details as possible. +For example, start by explaining how you started DiscImageChef, e.g. which command exactly +you used in the terminal. Also note that some device commands requires you to have +administrative privileges, be in a specific group, or be the root user, so try it again with +escalated privileges. +* **Provide specific examples to demonstrate the steps**. Include links to media images, +reports of the devices, or the output of using [DiscImageChef.Tests.Devices](https://github.com/claunia/DiscImageChef/tree/master/DiscImageChef.Tests.Devices). +* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. +* **Explain which behavior you expected to see instead and why.** +* **Include a copy of the output in the terminal** enabling both verbose, using the `-v` +command line parameter, and debug, using the `-d` command line parameter, outputs. +* **If you're reporting that DiscImageChef crashed**, try doing the same with the debug +version and include a crash report with a stack trace. Include the crash report in the issue +in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines), a +[file attachment](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/), +or put it in a [gist](https://gist.github.com/) and provide link to that gist. +* **If the problem wasn't triggered by a specific action**, describe what you were doing +before the problem happened and share more information using the guidelines below. + +Include details about your configuration and environment: + +* **Which version of DiscImageChef are you using?** +* **What's the name and version of the OS you're using**? +* **Are you running DiscImageChef in a virtual machine?** If so, which VM software are you +using and which operating systems and versions are used for the host and the guest? +* **Are you trying to execute a device command?** If so, who manufactured the device, which +model is it, and how is it connected to the computer. + +### Suggesting Enhancements + +This section guides you through submitting an enhancement suggestion for Atom, including +completely new features and minor improvements to existing functionality. Following these +guidelines helps maintainers and the community understand 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](ISSUE_TEMPLATE.md), including the steps that you imagine you would +take if the feature you're requesting existed. + +#### How Do I Submit A (Good) Enhancement Suggestion? + +Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). +After you've determined [which module](#discimagechef-and-modules) your enhancement suggestion +is related to, create an issue on that repository and provide the following information: + +* **Use a clear and descriptive title** for the issue to identify the suggestion. +* **Provide a step-by-step description of the suggested enhancement** in as many details as +possible. +* **Provide specific examples to demonstrate the steps**. If the feature is about a media image, +filesystem, partitioning scheme, or filter, please include as many test files as possible, +and if applicable which software created them. +* **Describe the current behavior** and **explain which behavior you expected to see instead** and why. +* **List some other applications where this enhancement exists.** +* **Specify which version of DiscImageChef you're using.** +* **Specify the name and version of the OS you're using.** + +### Your First Code Contribution + +Unsure where to begin contributing to DiscImageChef? You can start by looking through these `beginner` and `help-wanted` issues: + +* [Beginner issues][beginner] - issues which should only require a few lines of code, and a test or two. +* [Help wanted issues][help-wanted] - issues which should be a bit more involved than `beginner` issues. + +Both issue lists are sorted by total number of comments. While not perfect, number of +comments is a reasonable proxy for impact a given change will have. + +If you want to read about using DiscImageChef, the [wiki](https://github.com/claunia/DiscImageChef/wiki) is available. + +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. + +DiscImageChef 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. + +### Pull Requests + +* Fill in [the required template](PULL_REQUEST_TEMPLATE.md) +* Do not include issue numbers in the PR title +* Follow the [code styleguide](#code-styleguide). +* 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. +* Avoid platform-dependent code, unless absolutely needed. Any call to a part of the +.NET framework that doesn't start with `System.` is probably platform-dependent. +* Do not call libraries external to .NET. Only Interop calls to the operating system kernel +(that is `KERNEL32.DLL` in Windows and `libc` in others) will be accepted. If you need to +talk with a USB devices your pull request must implement calls both to `WinUsb` and `libusb`. + +### Patronizing +If you want to donate money you can become a patron at https://www.patreon.com/DiscImageChe + +This money will be used to get more hardware on which to test DiscImageChef. + +### Donating +You may donate us one of the [devices we need](DONATING.md). + +### Needed information +If you have test images, imaging applications that generate formats we do not support, or +documentation about media dump formats, filesystems or partitioning schemes we do not +support, you can provide us with that information to add support for them. + +## Styleguides + +### Git Commit Messages + +* 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 +* Reference issues and pull requests liberally after the first line +* Consider starting the commit message with an applicable emoji: + * :art: `:art:` when improving the format/structure of the code + * :racehorse: `:racehorse:` when improving performance + * :non-potable_water: `:non-potable_water:` when plugging memory leaks + * :memo: `:memo:` when writing docs + * :penguin: `:penguin:` when fixing something on Linux + * :apple: `:apple:` when fixing something on macOS + * :checkered_flag: `:checkered_flag:` when fixing something on Windows + * :bug: `:bug:` when fixing a bug + * :fire: `:fire:` when removing code or files + * :green_heart: `:green_heart:` when fixing the CI build + * :white_check_mark: `:white_check_mark:` when adding tests + * :lock: `:lock:` when dealing with security + * :arrow_up: `:arrow_up:` when upgrading dependencies + * :arrow_down: `:arrow_down:` when downgrading dependencies + * :shirt: `:shirt:` when removing linter warnings + +### Code Styleguide + +- Braces are unindented at next line (BSD style). +- Braces with no content should be opened and closed in the same line. +- Constants should be ALL_UPPER_CASE. +- Do not use braces for statements that don't need them. +- Do not use more than one blank line. +- Do not use spaces before or after parentheses. +- Do not use `var` ever. +- `else`, `while`, `catch` and `finally` should be on a new line. +- If you know C apply a simple rule: Be as C as and as less C# or C++ as possible. +- 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. +- Public fields should be UpperCamelCase. +- Separate attributes. +- Use 120 columns margins. +- Use built-in keywords: `uint` instead of `UInt32`. +- Use expression bodies only for properties, indexes and events. For the rest use block +bodies. +- Use implicit modifiers. +- Use inline variable declaration. +- Use struct implicit constructor. +- Use UNIX (`\n`) endline character. + +> Note: DiscImageChef is quite low-level so unneeded object-oriented abstractions +(e.g. using classes when a struct suffices) will be rejected. LINQ is accepted. \ No newline at end of file diff --git a/DiscImageChef/DiscImageChef.csproj b/DiscImageChef/DiscImageChef.csproj index e74b94388..737c3968e 100644 --- a/DiscImageChef/DiscImageChef.csproj +++ b/DiscImageChef/DiscImageChef.csproj @@ -167,10 +167,6 @@ .travis.yml - - CODING.md - PreserveNewest - CONTRIBUTING.md PreserveNewest @@ -182,10 +178,6 @@ NEEDINFO.md PreserveNewest - - TESTING.md - PreserveNewest - Changelog.md @@ -264,4 +256,11 @@ PreserveNewest + + + + + + + \ No newline at end of file diff --git a/README.md b/README.md index 32eb0998f..661120255 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,32 @@ Disc Image Chef (because "swiss-army-knife" is used too much) -Copyright © 2011-2017 Natalia Portillo +Copyright © 2011-2018 Natalia Portillo [![Build Status](https://travis-ci.org/claunia/DiscImageChef.svg?branch=master)](https://travis-ci.org/claunia/DiscImageChef)[![Build status](https://ci.appveyor.com/api/projects/status/vim4c8h028pn5oys?svg=true)](https://ci.appveyor.com/project/claunia/discimagechef) You can see statistics and device reports [here](http://discimagechef.claunia.com/Statistics.aspx) -If you want to donate money you can become a patron at https://www.patreon.com/DiscImageChef -If you want to donate hardware you can see [what we need](DONATING.md), but any kind of hardware donation will be accepted, thanks. +DiscImageChef is a fully featured media dump management solution. You usually know media dumps +as disc images, disk images, tape images, etc. + +With DiscImageChef you can analyze a media dump, extract files from it (for supported +filesystems), compare two of them, create them from real media using the appropriate drive, +create a sidecar metadata with information about the media dump, and a lot of other features +that commonly would require you to use separate applications. + To see last changes, check the [changelog](Changelog.md). To see list of pending things to do, check the [TODO list](TODO.md). +If you want to contribute in any way please read the [contributing guide](CONTRIBUTING.md). + +System requirements +=================== +DiscImageChef should work under any operating system where there is [Mono](http://www.mono-project.com/) +or [.NET Framework](https://www.microsoft.com/net/download). +It has been tested using Mono 3.0 and .NET Framework 4.0. However recommended versions are +Mono 5.0 and .NET Framework 4.6. .NET Core is untested. + Usage ===== @@ -21,7 +36,7 @@ DiscImageChef.exe And read help. -Works under any operating system where there is Mono or .NET Framework. Tested with Mono 3.0. +Or read the [wiki](https://github.com/claunia/DiscImageChef/wiki). Features ======== diff --git a/TESTING.md b/TESTING.md deleted file mode 100644 index 256b5e87d..000000000 --- a/TESTING.md +++ /dev/null @@ -1,22 +0,0 @@ -How to test and bug report -========================== - -First of all take in account that DiscImageChef master from git is unstable, prone to crashing and not working as expected, so don't suppose anything will work at all. -Specially compiling. - -Once you've taken that in account normal testing procedures apply. - -You must report bugs using GitHub issues facilities. - -Sending an email telling the bug is the perfect way to get it forgotten in oblivion. - -In the bug report you must indicate the following: -- Your operating system exact version, release and distribution -- The .NET Framework or Mono version you used to run DiscImageChef -- The exact command line used -- Expected results -- If DiscImageChef was used against a disk image you may need to provide us a copy -- If DiscImageChef was used against a device or physical media you may need to retest it several times - -When you create the issue I'll check it as soon as I can and provide feedback. -However, solving it, will enter in the current queue of things to do. \ No newline at end of file diff --git a/TODO.md b/TODO.md index 470c881e8..40b480bab 100644 --- a/TODO.md +++ b/TODO.md @@ -1,71 +1,92 @@ -Disc image plugins -================== -* Add support for DiscFerret images -* Add support for Kryoflux images -* Add support for XPACK images - -Filesystem plugins -================== -* Add support for NwFS -* Add support for ReFS - -Partitioning scheme plugins -=========================== -* Add support for AIX partitions - -RAW plugin -========== -* Finish support for reading sectors of variable bytes/sector images - -Image comparison -================ -* Compare sector tags -* Offer the option to see differing values -* Optimize and multithread - -Image checksum -============== +* Add checksum support for Apple NIB images. (https://github.com/claunia/DiscImageChef/issues/105) +* Add checksum support for NDIF images. (https://github.com/claunia/DiscImageChef/issues/88) +* Add checksum support for partclone images. (https://github.com/claunia/DiscImageChef/issues/89) +* Add checksum support for partimage images. (https://github.com/claunia/DiscImageChef/issues/90) +* Add detection of bootable UDF filesystems. (https://github.com/claunia/DiscImageChef/issues/91) +* Add filter for 7-Zip archives. (https://github.com/claunia/DiscImageChef/issues/92) +* Add filter for ZIP archives. (https://github.com/claunia/DiscImageChef/issues/93) +* Add flux decoding for DiscFerret images. (https://github.com/claunia/DiscImageChef/issues/49) +* Add flux decoding for KryoFlux images. (https://github.com/claunia/DiscImageChef/issues/50) +* Add flux decoding for SuperCardPro images. (https://github.com/claunia/DiscImageChef/issues/99) +* Add interface for floppy bitstream decoding. (https://github.com/claunia/DiscImageChef/issues/94) +* Add raw dump for Plextor recorders. (https://github.com/claunia/DiscImageChef/issues/100) +* Add support for 82077 floppy controllers. (https://github.com/claunia/DiscImageChef/issues/101) +* Add support for AIX partitioning scheme. (https://github.com/claunia/DiscImageChef/issues/7) +* Add support for Apple 2 character encoding. (https://github.com/claunia/DiscImageChef/issues/102) +* Add support for CD-Text in Nero images. (https://github.com/claunia/DiscImageChef/issues/104) +* Add support for compressed Ciscopy images. (https://github.com/claunia/DiscImageChef/issues/127) +* Add support for compressed DART images. (https://github.com/claunia/DiscImageChef/issues/68) +* Add support for compressed MAME CHD version 5 images. (https://github.com/claunia/DiscImageChef/issues/106) +* Add support for compressed MAME CompactDisc images. (https://github.com/claunia/DiscImageChef/issues/107) +* Add support for compressed NDIF images. (https://github.com/claunia/DiscImageChef/issues/68) +* Add support for compressed SaveDskF images. (https://github.com/claunia/DiscImageChef/issues/108) +* Add support for compressed UDIF images. (https://github.com/claunia/DiscImageChef/issues/70) +* Add support for compressed VMware images. (https://github.com/claunia/DiscImageChef/issues/109) +* Add support for CSS encrypted DVD dumping. (https://github.com/claunia/DiscImageChef/issues/110) +* Add support for decoding Apple GCR bitstreams. (https://github.com/claunia/DiscImageChef/issues/95) +* Add support for decoding Commodore GCR bitstreams. (https://github.com/claunia/DiscImageChef/issues/96) +* Add support for decoding FM bitstreams. (https://github.com/claunia/DiscImageChef/issues/97) +* Add support for decoding MFM bitstreams. (https://github.com/claunia/DiscImageChef/issues/98) +* Add support for detecting FireWire devices in FreeBSD. (https://github.com/claunia/DiscImageChef/issues/111) +* Add support for detecting FireWire devices in Windows. (https://github.com/claunia/DiscImageChef/issues/125) +* Add support for detecting USB devices in FreeBSD. (https://github.com/claunia/DiscImageChef/issues/112) +* Add support for differencing QCOW2 images. (https://github.com/claunia/DiscImageChef/issues/142) +* Add support for differencing QCOW images. (https://github.com/claunia/DiscImageChef/issues/143) +* Add support for differencing QED images. (https://github.com/claunia/DiscImageChef/issues/144) +* Add support for DiscFerret devices. (https://github.com/claunia/DiscImageChef/issues/140) +* Add support for dumping CD Lead-In in FreeBSD. (https://github.com/claunia/DiscImageChef/issues/113) +* Add support for encrypted NDIF images. (https://github.com/claunia/DiscImageChef/issues/149) +* Add support for encrypted QCOW2 images. (https://github.com/claunia/DiscImageChef/issues/145) +* Add support for encrypted QCOW images. (https://github.com/claunia/DiscImageChef/issues/146) +* Add support for encrypted VMware images. (https://github.com/claunia/DiscImageChef/issues/147) +* Add support for KryoFlux devices. (https://github.com/claunia/DiscImageChef/issues/141) +* Add support for Linear Media PCMCIA devices. (https://github.com/claunia/DiscImageChef/issues/148) +* Add support for MAME CHD images of PCMCIA devices. (https://github.com/claunia/DiscImageChef/issues/150) +* Add support for Microsoft Resilient filesystem (ReFS). (https://github.com/claunia/DiscImageChef/issues/13) +* Add support for NetApp WAFL filesystem. (https://github.com/claunia/DiscImageChef/issues/61) +* Add support for NetWare 286 filesystem. (https://github.com/claunia/DiscImageChef/issues/117) +* Add support for NetWare 386 filesystem. (https://github.com/claunia/DiscImageChef/issues/118) +* Add support for Novell Storage Services filesystem. (https://github.com/claunia/DiscImageChef/issues/119) +* Add support for NVMe devices. (https://github.com/claunia/DiscImageChef/issues/151) +* Add support for OCFS2 filesystem. (https://github.com/claunia/DiscImageChef/issues/153) +* Add support for packed subchannel in BlindWrite 4 images. (https://github.com/claunia/DiscImageChef/issues/154) +* Add support for packed subchannel in BlindWrite 5 images. (https://github.com/claunia/DiscImageChef/issues/155) +* Add support for Parallel ATA devices in FreeBSD. (https://github.com/claunia/DiscImageChef/issues/114) +* Add support for PCMCIA devices in FreeBSD. (https://github.com/claunia/DiscImageChef/issues/115) +* Add support for PCMCIA devices in Windows. (https://github.com/claunia/DiscImageChef/issues/126) +* Add support for Radix-50 character encoding. (https://github.com/claunia/DiscImageChef/issues/103) +* Add support for reading resource fork in macOS. (https://github.com/claunia/DiscImageChef/issues/156) +* Add support for reading resource fork in Windows. (https://github.com/claunia/DiscImageChef/issues/157) +* Add support for SecureDigital and MultiMediaCard devices in FreeBSD. (https://github.com/claunia/DiscImageChef/issues/116) +* Add support for Sharp X68000 FAT filesystem variation. (https://github.com/claunia/DiscImageChef/issues/158) +* Add support for SuperCardPro devices. (https://github.com/claunia/DiscImageChef/issues/139) +* Add support for Xia filesystem. (https://github.com/claunia/DiscImageChef/issues/152) +* Add support for XPACK images. (https://github.com/claunia/DiscImageChef/issues/45) +* Check CompactDisc read capabilities on dumping. (https://github.com/claunia/DiscImageChef/issues/138) * Checksum disk tags * Checksum long sectors * Checksum sector tags -* Optimize and multithread - -Device handling -=============== -* Add support for FreeBSD -* Add support for NVMe devices -* Add support for streaming tape devices +* Compare sector tags +* Finish support for reading sectors of variable bytes/sector images +* Graphical User Interface +* Handle UDIF image comments. (https://github.com/claunia/DiscImageChef/issues/137) +* Implement Apple KenCode compression algorithm. (https://github.com/claunia/DiscImageChef/issues/122) +* Implement Apple LZFSE compression algorithm. (https://github.com/claunia/DiscImageChef/issues/124) +* Implement Apple LZH compression algorithm. (https://github.com/claunia/DiscImageChef/issues/121) +* Implement Apple RLE compression algorithm. (https://github.com/claunia/DiscImageChef/issues/120) +* Implement COLUMBIA ordering in CP/M filesystem. (https://github.com/claunia/DiscImageChef/issues/133) +* Implement conversion of dump formats. (https://github.com/claunia/DiscImageChef/issues/134) +* Implement CYLINDERS ordering in CP/M filesystem. (https://github.com/claunia/DiscImageChef/issues/132) +* Implement dumping GameCube discs. (https://github.com/claunia/DiscImageChef/issues/135) +* Implement dumping Wii discs. (https://github.com/claunia/DiscImageChef/issues/136) +* Implement EAGLE ordering in CP/M filesystem. (https://github.com/claunia/DiscImageChef/issues/131) +* Implement ODS checksum. (https://github.com/claunia/DiscImageChef/issues/130) +* Implement StuffIt compression algorithm. (https://github.com/claunia/DiscImageChef/issues/123) +* Implement writing support for dump formats. (https://github.com/claunia/DiscImageChef/issues/129) +* Offer the option to see differing values +* Optimize and multithread image comparison +* Optimize current checksum multithreading +* Support AAP extensions in MBR. (https://github.com/claunia/DiscImageChef/issues/159) +* Support IBM boot manager in MBR. (https://github.com/claunia/DiscImageChef/issues/128) * Support MMC feature codes FF33h -* Support SCSI mode pages 18h, 1Dh, 20h, 31h, 32h - -QCOW plugin -=========== -* Add support for encrypted images - -VMDK plugin -=========== -* Add support for encrypted extents -* Add support for compressed extents - -UDIF plugin -=========== -* Add support for chunks compressed with RLE, LZH, KenCode or LZFSE - -NDIF plugin -=========== -* Add support for chunks compressed with RLE, LZH or KenCode - -DART plugin -=========== -* Add support for chunks compressed with RLE or LZH - -CHD plugin -========== -* Add support for PCMCIA images -* Add support for compressed hunks on CD disc images -* Add support for compressed version 5 disk images - -Filters -======= -* Add support for 7Z archives -* Add support for ZIP archives \ No newline at end of file +* Support SCSI mode pages 18h, 1Dh, 20h, 31h, 32h \ No newline at end of file