From b7bd9a7a45a373f73f9917b62b024b3bccff20aa Mon Sep 17 00:00:00 2001 From: NeotericSh Date: Sun, 25 Aug 2024 23:09:29 +0200 Subject: [PATCH 1/5] Add contributing guidelines --- CONTRIBUTING.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5de5a6e6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,168 @@ + +#
Contributing toNetPad
+ +Last updated: August 25th, 2024 :book: + +Thank you for considering contributing to **NetPad**! We’re excited to have you join the project. + +- [How to Contribute](#how-to-contribute-star) +- [Submitting Changes](#submitting-changes) +- [Creating a Development Environment](#creating-a-development-environment) + - [Prerequisites](#prerequisites) + - [Manually Start the Project](#manually-start-the-project) + - [NetPad as an Electron desktop app](#netpad-as-an-electron-desktop-app-wrench) + - [NetPad as a Web App (accessed from a browser)](#netpad-as-a-web-app-accessed-from-a-browser-spider_web) + - [Packaging](#packaging-package) +- [Issue Reporting](#issue-reporting) +- [Documentation Guidelines](#documentation-guidelines) +- [License](#license) +- [Contact](#contact) +- [Acknowledgments](#acknowledgments) + +## How to Contribute :star: +- Report bugs or request features through the [issue tracker](https://github.com/tareqimbasher/NetPad/issues). +- [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the repository, [create a branch](https://git-scm.com/docs/git-checkout), make your [changes](https://stackoverflow.com/questions/76776374/how-do-i-add-commit-and-push-code-to-git-using-git-bash-command-at-once#answer-76776375), and submit a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to the `main` branch. + +## Submitting Changes +- **Branching Strategy**: Create a feature branch for your work. For example, `feat/my-new-feature`. +- **Commit Messages**: Follow this format: `Add contributing guidelines`. +- **Pull Requests**: Ensure your PR includes **tests** and follows our coding standards. A small **description** of the changes as well as the **issue number** (if applicable). + +### Pull request example :arrow_down: + +> Added contributing guidelines to make it easier for new contributors to get started. +> +> **Changes Made:** +> +> - Added a new CONTRIBUTING.md file. +> - Updated the README.md file to include a link to the new CONTRIBUTING.md file. + +## Creating a Development Environment +### Prerequisites +- [Node](https://nodejs.org/en/download/prebuilt-installer/current) v16+ (npm v8+) +- [.NET](https://dotnet.microsoft.com/en-us/download/dotnet/7.0) SDK 7.x +- [EF Core tools](https://learn.microsoft.com/en-us/ef/core/cli/dotnet) (.NET 5 or later) + +### Manually Start the Project +1. Fork and clone the repository and navigate to the project directory. +```bash +git clone https://github.com//NetPad.git && cd NetPad +``` + +#### NetPad as an Electron desktop app :wrench: + +1. Run the SPA (Single Page Application) + +```bash +# Install dependencies +cd src/Apps/NetPad.Apps.App/ElectronHostHook +npm install + +cd ../App +npm install + +# Start the development web server +npm start +``` + +2. Run the .NET app +Install the Electron.NET CLI tool + +> [!IMPORTANT] +> To be able to run the elextronize command with Electron.NET CLI, you need to have .NET 6 SDK installed. + +```bash +dotnet tool install ElectronNET.CLI -g +``` + +3. Start the app + +> [!NOTE] +> Only the very first `electronize start` is slow. Later runs are much faster! + +```bash +cd src/Apps/NetPad.Apps.App/ + +# Start in watch mode (remove '/watch' to run without watch mode) +electronize start /watch /manifest electron.manifest.dev.js + +# For macOS ARM, append the following to the 'electronize start' command +/target custom "osx-arm64;mac" /electron-arch arm64 +``` + +#### NetPad as a Web App (accessed from a browser) :spider_web: + +> [!NOTE] +> SQLite database connections are not supported when NetPad is ran as a web app in the browser. + +1. Run the SPA (Single Page Application) + +```bash +# Install dependencies +cd src/Apps/NetPad.Apps.App/ +npm install +``` + +2. Start the development web server +```bash +cd src/Apps/NetPad.Apps.App/ +dotnet watch run --environment Development +``` + +Access the app via your web browser at [http://localhost:57940](http://localhost:57940). + +### Packaging :package: + +The Electron app is built and packaged using +[electron-builder](https://www.electron.build/). Configuration is in the `electron.manifest.js` +file. + +Build the app for the desired platform from the root directory of the `NetPad.Apps.App` project: + +```bash +# For x64: +electronize build /target win /manifest electron.manifest.js /PublishSingleFile false +electronize build /target osx /manifest electron.manifest.js /PublishSingleFile false +electronize build /target linux /manifest electron.manifest.js /PublishSingleFile false + +# For macOS ARM: +electronize build /target custom "osx-arm64;mac" /electron-arch arm64 /manifest electron.manifest.js /PublishSingleFile false +``` + +Packaged files can be found in the `bin/Desktop` folder. + +> [!NOTE] +> To Build flatpak files the flatpak` and `flatpak-builder` packages need to be installed. +> On Linux, the `/scripts/package-electron.sh` script can be used + > to package the Electron app, in which case packaged files can be found in + > the `/dist/` folder. + +See the [Electron.NET docs](https://github.com/ElectronNET/Electron.NET#-build) +for additional CLI options when packaging the app, +and [electron-builder](https://www.electron.build/) for additional configuration +options. + +## Issue Reporting +- **Bug Reports**: Include steps to reproduce and environment details. +- **Feature Requests**: Clearly describe the feature and why it’s needed. + +## Documentation Guidelines +Documentation contributions are welcome. And includes in the `/docs` directory as well as in the [README.md](./README.md) and [CONTRIBUTING.md](./CONTRIBUTING.md) files. + +* Don't add images or other media files with excessive size. +* Use [camelCase](https://en.wikipedia.org/wiki/Camel_case) for directory names. +* Use [Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case) for file names. + +> [!IMPORTANT] +> The naming conventions mentioned above do not apply for the .NET projects nor the Electron projects. Follow the conventions of the respective technologies. + +## License +By contributing, you agree that your contributions will be licensed under the [MIT LICENSE](./LICENSE). + +## Contact +If you have any questions, feel free to open an issue or contact us at our [Discord Server](https://discord.gg/FrgzNBYQFW) + +At our Discord, you can find the latest announcements, troubleshooting, ideas and feedback, and more. + +## Acknowledgments +
Thank you for your contributions and helping makeNetPad better!
From 3ad2dfa2c8885f6ad98d20ce1c0f179c2d2b7543 Mon Sep 17 00:00:00 2001 From: NeotericSh Date: Sun, 25 Aug 2024 23:09:56 +0200 Subject: [PATCH 2/5] Update readme to link to contributing guidelines --- README.md | 109 ++---------------------------------------------------- 1 file changed, 4 insertions(+), 105 deletions(-) diff --git a/README.md b/README.md index 0e3908a8..49fc73c3 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ the Wiki. ## Contribution -All Pull Requests, feedback and contributions are welcome! +All Pull Requests, feedback and contributions are welcome! Please read the [Contributing guidelines](./CONTRIBUTING.md) for more information about how to contribute and build/run the project. Also a special thanks to the NetPad's wonderful sponsors. Sponsorships help pay for macOS builds and helps me maintain this project. @@ -174,113 +174,12 @@ and SignalR. ## Build -This section describes how to build and run NetPad from source. -NetPad can be run as an Electron desktop app or as a web application -accessed with a web browser. - -### Requirements - -* Node v16+ (npm v8+) -* .NET SDK 7.x -* EF Core tools 5.x or later - -### NetPad as an Electron desktop app - -#### 1. Run the SPA - -``` -# Install dependencies -cd src/Apps/NetPad.Apps.App/ElectronHostHook -npm install - -cd ../App -npm install - -# Start the development web server -npm start -``` - -#### 2. Run the .NET app - -Install the Electron.NET CLI tool: - -``` -dotnet tool install ElectronNET.CLI -g -``` - -Start the app: - -``` -cd src/Apps/NetPad.Apps.App - -# Start in watch mode (remove '/watch' to run without watch mode) -electronize start /watch /manifest electron.manifest.dev.js - -# For macOS ARM, append the following to the 'electronize start' command -/target custom "osx-arm64;mac" /electron-arch arm64 -``` - -###### Note - -> Only the very first `electronize start` is slow. Later runs are much faster. - -### NetPad as a Web app (accessed from a browser) - -#### 1. Run the SPA - -``` -# Install dependencies -cd Apps/NetPad.Apps.App/App -npm install - -# Start the development web server -npm run start-web -``` - -#### 2. Run the .NET app - -``` -cd Apps/NetPad.Apps.App -dotnet watch run --environment Development -``` - -and access the app via your web browser, ex: `http://localhost:57940` - -## Packaging :package: - -The Electron app is built and packaged using -[electron-builder](https://www.electron.build/). Configuration is in the `electron.manifest.js` -file. - -Build the app for the desired platform from the root directory of the `NetPad.Apps.App` project: - -``` -# For x64: -electronize build /target win /manifest electron.manifest.js /PublishSingleFile false -electronize build /target osx /manifest electron.manifest.js /PublishSingleFile false -electronize build /target linux /manifest electron.manifest.js /PublishSingleFile false - -# For macOS ARM: -electronize build /target custom "osx-arm64;mac" /electron-arch arm64 /manifest electron.manifest.js /PublishSingleFile false -``` - -Packaged files can be found in the `bin/Desktop` folder. - -###### Notes - -> 1. To build flatpak files the `flatpak` and `flatpak-builder` packages need to be installed. -> 2. On Linux, the `/scripts/package-electron.sh` script can be used - > to package the Electron app, in which case packaged files can be found in - > the `/dist/` folder. - - -See the [Electron.NET docs](https://github.com/ElectronNET/Electron.NET#-build) -for additional CLI options when packaging the app, -and [electron-builder](https://www.electron.build/) for additional configuration -options. +See [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on how to build and run NetPad from +source. NetPad can be ran as an Electron desktop app or as a web application accessed with a web browser. ## Resources :books:: * Docs: [Go](https://github.com/tareqimbasher/NetPad/tree/main/docs) * More on SPA app startup and running tests: [Go](https://github.com/tareqimbasher/NetPad/tree/main/src/Apps/NetPad.Apps.App/App) +* Build: [Go](./CONTRIBUTING.md#manually-start-the-project) From 71685ff0647695e46b34e2388216762b242cfbe1 Mon Sep 17 00:00:00 2001 From: NeotericSh Date: Mon, 26 Aug 2024 13:37:23 +0200 Subject: [PATCH 3/5] Fix spelling of electron command --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5de5a6e6..c6689772 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,7 +69,7 @@ npm start Install the Electron.NET CLI tool > [!IMPORTANT] -> To be able to run the elextronize command with Electron.NET CLI, you need to have .NET 6 SDK installed. +> To be able to run the electronize command with Electron.NET CLI, you need to have .NET 6 SDK installed. ```bash dotnet tool install ElectronNET.CLI -g From 02ec4bd3525a82bbbb89cf6b3efc366456fd958c Mon Sep 17 00:00:00 2001 From: NeotericSh Date: Mon, 26 Aug 2024 14:54:03 +0200 Subject: [PATCH 4/5] Fix spacing issue on flatpak note --- CONTRIBUTING.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6689772..8a2c77cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -132,10 +132,7 @@ electronize build /target custom "osx-arm64;mac" /electron-arch arm64 /manifest Packaged files can be found in the `bin/Desktop` folder. > [!NOTE] -> To Build flatpak files the flatpak` and `flatpak-builder` packages need to be installed. -> On Linux, the `/scripts/package-electron.sh` script can be used - > to package the Electron app, in which case packaged files can be found in - > the `/dist/` folder. +> To Build `flatpak` files the `flatpak` and `flatpak-builder` packages need to be installed. On Linux, the `/scripts/package-electron.sh` script can be used to package the Electron app, in which case packaged files can be found in the `/dist/` folder. See the [Electron.NET docs](https://github.com/ElectronNET/Electron.NET#-build) for additional CLI options when packaging the app, @@ -165,4 +162,4 @@ If you have any questions, feel free to open an issue or contact us at our [Disc At our Discord, you can find the latest announcements, troubleshooting, ideas and feedback, and more. ## Acknowledgments -
Thank you for your contributions and helping makeNetPad better!
+
Thank you for your contributions and helping make NetPad better!
From 194cc2fdea0f5f01b48235f9553ee522a22cd77a Mon Sep 17 00:00:00 2001 From: NeotericSh Date: Mon, 26 Aug 2024 16:15:56 +0200 Subject: [PATCH 5/5] Fix spacing for logo --- CONTRIBUTING.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a2c77cf..f69f39a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,4 @@ - -#
Contributing toNetPad
+

Contributing to  NetPad

Last updated: August 25th, 2024 :book: @@ -162,4 +161,4 @@ If you have any questions, feel free to open an issue or contact us at our [Disc At our Discord, you can find the latest announcements, troubleshooting, ideas and feedback, and more. ## Acknowledgments -
Thank you for your contributions and helping make NetPad better!
+
Thank you for your contributions and helping make  NetPad better!
\ No newline at end of file