|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## Project Scope |
| 4 | + |
| 5 | +The Electron.NET project ultimately tries to provide a framework for developing cross-platform client applications on the basis of .NET and Electron. Anything that is related to this goal will be considered. The project aims to be as close to Electron with .NET as a basis as possible. If your contribution does not reflect that goal, the chances of accepting it are limited. |
| 6 | + |
| 7 | +## Code License |
| 8 | + |
| 9 | +This is an open source project falling under the [MIT License](../LICENSE). By using, distributing, or contributing to this project, you accept and agree that all code within the Electron.NET project and its libraries are licensed under MIT license. |
| 10 | + |
| 11 | +## Becoming a Contributor |
| 12 | + |
| 13 | +Usually appointing someone as a contributor follows this process: |
| 14 | + |
| 15 | +1. An individual contributes actively via discussions (reporting bugs, giving feedback to existing or opening new issues) and / or pull requests |
| 16 | +2. The individual is either directly asked, invited or asks for contributor rights on the project |
| 17 | +3. The individual uses the contribution rights to sustain or increase the active contributions |
| 18 | + |
| 19 | +Every contributor might have to sign the contributor's license agreement (CLA) to establish a legal trust between the project and its contributors. |
| 20 | + |
| 21 | +## Working on Electron.NET |
| 22 | + |
| 23 | +### Issue Discussion |
| 24 | + |
| 25 | +Discussion of issues should be placed transparently in the issue tracker here on GitHub. |
| 26 | + |
| 27 | +* [General issues, bugs, new features](https://github.com/ElectronNET/Electron.NET/issues) |
| 28 | +* [General discussions, help, exchange of ideas](https://github.com/ElectronNET/Electron.NET/discussions) |
| 29 | + |
| 30 | +### Modifying the code |
| 31 | + |
| 32 | +Electron.NET and its libraries uses features from the latest versions of C# (e.g., C# 10). You will therefore need a C# compiler that is up for the job. |
| 33 | + |
| 34 | +1. Fork and clone the repo. |
| 35 | +2. First try to build the ElectronNET.Core library and see if you get the tests running. |
| 36 | +3. You will be required to resolve some dependencies via NuGet. |
| 37 | + |
| 38 | +The build system of Electron.NET uses NUKE. |
| 39 | + |
| 40 | +### Code Conventions |
| 41 | + |
| 42 | +Most parts in the Electron.NET project are fairly straight forward. Among these are: |
| 43 | + |
| 44 | +* Always use statement blocks for control statements, e.g., in a for-loop, if-condition, ... |
| 45 | +* You may use a simple (throw) statement in case of enforcing contracts on argument |
| 46 | +* Be explicit about modifiers (some files follow an older convention of the code base, but we settled on the explicit style) |
| 47 | + |
| 48 | +### Development Workflow |
| 49 | + |
| 50 | +1. If no issue already exists for the work you'll be doing, create one to document the problem(s) being solved and self-assign. |
| 51 | +2. Otherwise please let us know that you are working on the problem. Regular status updates (e.g. "still in progress", "no time anymore", "practically done", "pull request issued") are highly welcome. |
| 52 | +3. Create a new branch—please don't work in the `main` branch directly. It is reserved for releases. We recommend naming the branch to match the issue being addressed (`feature/#777` or `issue-777`). |
| 53 | +4. Add failing tests for the change you want to make. Tests are crucial and should be taken from W3C (or other specification). |
| 54 | +5. Fix stuff. Always go from edge case to edge case. |
| 55 | +6. All tests should pass now. Also your new implementation should not break existing tests. |
| 56 | +7. Update the documentation to reflect any changes. (or document such changes in the original issue) |
| 57 | +8. Push to your fork or push your issue-specific branch to the main repository, then submit a pull request against `develop`. |
| 58 | + |
| 59 | +Just to illustrate the git workflow for Electron.NET a little bit more we've added the following graphs. |
| 60 | + |
| 61 | +Initially, Electron.NET starts at the `main` branch. This branch should contain the latest stable (or released) version. |
| 62 | + |
| 63 | +Here we now created a new branch called `develop`. This is the development branch. |
| 64 | + |
| 65 | +Now active work is supposed to be done. Therefore a new branch should be created. Let's create one: |
| 66 | + |
| 67 | +```sh |
| 68 | +git checkout -b feature/#777 |
| 69 | +``` |
| 70 | + |
| 71 | +There may be many of these feature branches. Most of them are also pushed to the server for discussion or synchronization. |
| 72 | + |
| 73 | +```sh |
| 74 | +git push -u origin feature/#777 |
| 75 | +``` |
| 76 | + |
| 77 | +Now feature branches may be closed when they are done. Here we simply merge with the feature branch(es). For instance the following command takes the `feature/#777` branch from the server and merges it with the `develop` branch. |
| 78 | + |
| 79 | +```sh |
| 80 | +git checkout develop |
| 81 | +git pull |
| 82 | +git pull origin feature/#777 |
| 83 | +git push |
| 84 | +``` |
| 85 | + |
| 86 | +Finally, we may have all the features that are needed to release a new version of Electron.NET. Here we tag the release. For instance for the 1.0 release we use `v1.0`. |
| 87 | + |
| 88 | +```sh |
| 89 | +git checkout main |
| 90 | +git merge develop |
| 91 | +git tag v1.0 |
| 92 | +``` |
| 93 | + |
| 94 | +(The last part is automatically performed by our CI system. Don't tag manually.) |
| 95 | + |
| 96 | +### Versioning |
| 97 | + |
| 98 | +The rules of [semver](http://semver.org/) don't necessarily apply here, but we will try to stay quite close to them. |
| 99 | + |
| 100 | +Prior to version 1.0.0 we use the following scheme: |
| 101 | + |
| 102 | +1. MINOR versions for reaching a feature milestone potentially combined with dramatic API changes |
| 103 | +2. PATCH versions for refinements (e.g. performance improvements, bug fixes) |
| 104 | + |
| 105 | +After releasing version 1.0.0 the scheme changes to become: |
| 106 | + |
| 107 | +1. MAJOR versions at maintainers' discretion following significant changes to the codebase (e.g., API changes) |
| 108 | +2. MINOR versions for backwards-compatible enhancements (e.g., performance improvements) |
| 109 | +3. PATCH versions for backwards-compatible bug fixes (e.g., spec compliance bugs, support issues) |
| 110 | + |
| 111 | +#### Code style |
| 112 | + |
| 113 | +Regarding code style like indentation and whitespace, **follow the conventions you see used in the source already.** In general most of the [C# coding guidelines from Microsoft](https://msdn.microsoft.com/en-us/library/ff926074.aspx) are followed. This project prefers type inference with `var` to explicitly stating (redundant) information. |
| 114 | + |
| 115 | +It is also important to keep a certain `async`-flow and to always use `ConfigureAwait(false)` in conjunction with an `await` expression. |
| 116 | + |
| 117 | +## Backwards Compatibility |
| 118 | + |
| 119 | +We always try to remain backwards compatible beyond the currently supported versions of .NET. |
| 120 | + |
| 121 | +For instance, in December 2025 there have been activity to remove .NET 6 support from the codebase. We rejected this. Key points: |
| 122 | + |
| 123 | +1. We have absolutely no need to drop `.net6` support. It doesn't hurt us in any way. |
| 124 | +2. Many are still using `.net6`, including Electron.NET (non-Core) users. It doesn't make sense to force them to update two things at the same time (.NET + Electron.NET). |
| 125 | +3. We MUST NOT and NEVER update `Microsoft.Build.Utilities.Core`. This will make Electron.NET stop working on older Visual Studio and MSBuild versions. There's are also no reasons to update it in the first place. |
| 126 | + |
| 127 | +It's important to note that the Microsoft label of "Out of support" on .NET has almost no practical meaning. We've rarely (if ever) seen any bugs fixed in the same .NET version which mattered. The bugs that all new .NET versions have are much worse than mature .NET versions which are declared as "out of support". Keep in mind that the LTS matters most for active development / ongoing supported projects. If, e.g., a TV has been released a decade ago it most likely won't be patched. Still, you might want to deploy applications to it, which then naturally would involve being based on "out of support" versions of the framework. |
| 128 | + |
| 129 | +TL;DR: Unless there is a technical reason (e.g., a crucial new API not being available) we should not drop "out of support" .NET versions. At the time of writing (December 2025) the minimum supported .NET version remains at `.net6`. |
| 130 | + |
| 131 | +## Timeline |
| 132 | + |
| 133 | +**All of this information is related to ElectronNET.Core pre-v1!** |
| 134 | + |
| 135 | +We pretty much release whenever we have something new (i.e., do fixes such as a 0.1.1, or add new features, such as a 0.2.0) quite quickly. |
| 136 | + |
| 137 | +We will go for a 1.0.0 release of this as early as ~mid of January 2026 (unless we find some critical things or want to extend the beta phase for ElectronNET.Core). This should be sufficient time to get some user input and have enough experience to call it stable. |
0 commit comments