Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update CONTRIBUTING.md #472

Merged
merged 1 commit into from Mar 28, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@ You can contribute to DevToys app by:
- Internationalization and localization:
* See instructions below.

# How to Build and Run DevToys from source
# How to Build and Run DevToys from source:

* Make sure your machine is running on Windows 10 1903+.
* Make sure you have Visual Studio 2019 16.10+ or Visual Studio 2022 17.0+ installed.
* In Visual Studio Installer, install the required components by importing the [vs2022.vsconfig](vs2022.vsconfig) or [vs2019.vsconfig](vs2019.vsconfig) file.
* In Visual Studio Installer, install the required components by importing the [vs2022.vsconfig](vs2022.vsconfig) or [vs2019.vsconfig](vs2019.vsconfig) file.
* Run `init.ps1` in a PowerShell command prompt to restore all the dependencies.
* Open `src/DevToys.sln` with Visual Studio and set Solution Platform to x64*.
* Once opened, set `src/dev/DevToys.Startup/DevToys.Startup.wapproj` as startup project.
* Now you should be able to build and run DevToys on your machine. If it fails, try close the solution and reopen it again.
* Now you should be able to build and run DevToys on your machine. If it fails, try to close the solution and reopen it again.

**If x64 doesn't work, use the architecture of your system*

Expand All @@ -24,17 +24,17 @@ You can contribute to DevToys app by:
* After following `How to Build and Run DevToys from source`, close Visual Studio, if any instance is running.
* In File Explorer, copy the folder `dev/impl/DevToys/Strings/en-US` and rename the copied folder with the language indication of your choice. For example, "fr-FR" for French (France).
* Open `src/DevToys.sln` with Visual Studio.
* Open each `.resw` files from the language folder you created and translate the text.
* Open each `.resw` file from the language folder you created and translate the text.
* Build and Run the app and test your changes.

# Coding

## Main architecture

DevToys is using [MEF](https://docs.microsoft.com/en-us/dotnet/framework/mef/) as dependency injection framework.
Every tools available (i.e Base64 Encoder/Decoder, JSON Formatter, Settings...) are dynamically discovered and instanciated through MEF. A tool is divided in 3 components:
DevToys is using [MEF](https://docs.microsoft.com/en-us/dotnet/framework/mef/) as a dependency injection framework.
Every tool available (i.e Base64 Encoder/Decoder, JSON Formatter, Settings...) are dynamically discovered and instantiated through MEF. A tool is divided in 3 components:
1. [IToolProvider](https://github.com/veler/DevToys/blob/main/src/dev/impl/DevToys/Api/Tools/IToolProvider.cs) and its metadata, which represents the tool as displayed in the main menu in the app. `IToolProvider` should be MEF exported.
2. [IToolViewModel](https://github.com/veler/DevToys/blob/main/src/dev/impl/DevToys/Api/Tools/IToolViewModel.cs), which is a ViewModel as described by [MVVM](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel) pattern in UWP. It doesn't have to be MEF exported but may be required depending on what the tool needs to work.
2. [IToolViewModel](https://github.com/veler/DevToys/blob/main/src/dev/impl/DevToys/Api/Tools/IToolViewModel.cs), which is a ViewModel as described by the [MVVM](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel) pattern in UWP. It doesn't have to be MEF exported but may be required depending on what the tool needs to work.
3. A `Page` that represents the view of the tool.

The tool provider is instantiated when the app starts. The view and view models are instantiated when the user selects the tool in the main menu.
Expand All @@ -51,15 +51,15 @@ You can find the attributes [here](https://github.com/veler/DevToys/tree/main/sr

## Sample

A good tool to take example on is `Json <> Yaml` converter.
A good tool to take an example on is `Json <> Yaml` converter.
* [The tool provider](https://github.com/veler/DevToys/blob/main/src/dev/impl/DevToys/ViewModels/Tools/Converters/JsonYaml/JsonYamlToolProvider.cs)
* [The view model](https://github.com/veler/DevToys/blob/main/src/dev/impl/DevToys/ViewModels/Tools/Converters/JsonYaml/JsonYamlToolViewModel.cs)
* [The view](https://github.com/veler/DevToys/tree/main/src/dev/impl/DevToys/Views/Tools/Converters/JsonYaml)

## Things to keep in mind

We try to avoid at maximum to use any UWP capability/permission like `internet`, `camera`, `location`...etc. The reason why is that this app is designed to be tool that we can **trust** when pasting sensitive data inside.
Therefore, when doing changes to DevToys, please try at maximum to avoid any capability requirement.
We try to avoid at maximum any UWP capability/permission like `internet`, `camera`, `location`...etc. The reason why is that this app is designed to be a tool that we can **trust** when pasting sensitive data inside.
Therefore, when making changes to DevToys, please try at maximum to avoid any capability requirement.

## Code Style

Expand All @@ -75,15 +75,15 @@ Therefore, when doing changes to DevToys, please try at maximum to avoid any cap

4. DO NOT use Hungarian notation.

5. DO NOT use underscores, hyphens, or any other nonalphanumeric characters.
5. DO NOT use underscores, hyphens, or any other non-alphanumeric characters.

6. DO NOT use Caps for any names.

7. DO use predefined type names like `int`, `string` etc. instead of `Int32`, `String`.

8. DO use `_` prefix for private field names.

9. DO use `I` prefix for Interface names.
9. DO use the `I` prefix for Interface names.

10. DO vertically align curly brackets.

Expand Down