From 546535bd737a19ee67ffcdb45af9857ac83398af Mon Sep 17 00:00:00 2001 From: TC Johnson Date: Thu, 20 Jul 2023 22:49:26 -0500 Subject: [PATCH 1/2] Add contributor guide and code of conduct markdown documents --- CONTRIBUTING.md | 97 ++++++++++++++++++++++++++++++++ README.md | 2 + code_of_conduct.md | 134 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 233 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 code_of_conduct.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ba7e420f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# Contributing to Veilid +Before you get started, please review our [Code of Conduct](./CODE_OF_CONDUCT.md). We're here to make things better and we cannot do that by treating each other without respect. + + +## Code Contributions +To begin crafting code to contribution to the Veilid project, first set up a [development environment]. After cloning the project, check out a new local branch and name it in a way that describes the work being done. This is refered to as a topic branch. + +Some contributions might introduce changes that are incompatible with other existing nodes. In this case it is recommended to also set a [development network]. *NEED TO WRITE* + +Once you have added your new function or addressed a bug, test it locally to ensure it's working as expected. If needed, test your work in a development network with more than one node based on your code. Once you're satisfied your code works as intended and does not introduce negative results or new bugs, follow the merge requests section below to submit your work for maintainer review. + +We try to consider all merge requests fairly and with attention deserving to those willing to put in time and effort, but if you do not follow these rules, your contribution +will be closed. We strive to ensure that the code joining the main branch is written to a high standard. + + +### Code Contribution Do's & Don'ts: + +Keeping the following in mind gives your contribution the best chance of landing! + +#### Merge Requests + +* **Do** create a [topic branch] to work on instead of working directly on `main`. This helps to: + * Protect the process. + * Ensures users are aware of commits on the branch being considered for merge. + * Allows for a location for more commits to be offered without mingling with other contributor changes. + * Allows contributors to make progress while a PR is still being reviewed. +* **Do** follow the [50/72 rule] for Git commit messages. +* **Do** target your merge request to the **main branch**. +* **Do** specify a descriptive title to make searching for your merge request easier. +* **Do** list [verification steps] so your code is testable. +* **Do** [reference associated issues] in your merge request description. +* **Don't** leave your merge request description blank. +* **Don't** abandon your merge request. Being responsive helps us land your code faster. +* **Don't** submit unfinished code. + + + +## Contributions Without Writing Code +There are numerous ways you can contribute to the growth and success of the Veilid project without writing code: + + - [submit]() bugs as well as feature/enhancement requests. Letting us know you found a bug, have an idea for a new feature, or see a way we can enhance existing features is just as important and useful as writing the code related to those things. Send us detailed information about your issue or idea: + - Features/Enhancements: Describe your idea. If you're able to, sketch out a diagram or mock-up. + - Bugs: Please be sure to include the expected behavior, the observed behavior, and steps to reproduce the problem. Please be descriptive about the environment you've installed your node or application into. More information can be found [below](#bug-reports). + - [Help other users with open issues]. Sometimes all an issue needs is a little conversation to clear up a process or misunderstanding. Please keep the [Code of Conduct](./CODE_OF_CONDUCT.md) in mind. + - Help other contributors test recently submitted merge requests. By pulling down a merge request and testing it, you can help validate new code contributions for stability and quality. + - Report a security or privacy vulnerability. Please let us know if you find ways in which Veilid could handle security and/or privacy in a different or better way. Surely let us know if you find broken or otherwise flawed security and/or privacy functions. You can report these directly to security@veilid.org or by using the form found [on our site]() *NEED TO BUILD* + - Add or edit documentation. Documentation is a living and evolving library of knowledge. As such, care, feeding, and even pruning is needed from time to time. If you're a non-native english speaker, you can help by replacing any ambiguous idioms, metaphors, or unclear language that might make our documentation hard to understand. + + +#### Bug Fixes +* **Do** include reproduction steps in the form of verification steps. +* **Do** link to any corresponding [Issues] in the format of `See #1234` in your commit description. + +## Bug Reports + +Please report vulnerabilities in Veilid directly to security@veilid.org or by using the form found [on our site]() *NEED TO BUILD*. More information about our disclosure policy and Veilid Foundation's approach to coordinated disclosure can be found [on our site](). *NEED TO WRITE* + +When reporting Veilid issues: +* **Do** write a detailed description of your bug and use a descriptive title. +* **Do** include reproduction steps, stack traces, and anything that might help us fix your bug. +* **Don't** file duplicate reports. Search open issues for similar bugs before filing a new report. +* **Don't** attempt to report issues on a closed PR. New issues should be openned against the `main` branch. + +If you're looking for more guidance, talk to other Veilid contributors on the [Veilid Discord]. + +**Thank you** for taking the few moments to read this far! Together we will build something truely remarkable. + + + +This contributor guide is inspired by the contribution guidelines of the [Metasploit Framework](https://github.com/rapid7/metasploit-framework/blob/master/CONTRIBUTING.md) project found on GitHub. + +[Code of Conduct]:https://docs.metasploit.com/docs/code-of-conduct.html +[Submit bugs and feature requests]:http://r-7.co/MSF-BUGv1 +[Help fellow users with open issues]:https://github.com/rapid7/metasploit-framework/issues +[help fellow committers test recently submitted merge requests]:https://github.com/rapid7/metasploit-framework/pulls +[Report a security vulnerability in Metasploit itself]:https://www.rapid7.com/disclosure.jsp +[development environment]:http://r-7.co/MSF-DEV +[proof-of-concept exploits]:https://www.exploit-db.com/search?verified=true&hasapp=true&nomsf=true +[Ruby style guide]:https://github.com/bbatsov/ruby-style-guide +[Rubocop]:https://rubygems.org/search?query=rubocop +[50/72 rule]:http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +[topic branch]:http://git-scm.com/book/en/Git-Branching-Branching-Workflows#Topic-Branches +[draft PR]:https://help.github.com/en/articles/about-pull-requests#draft-pull-requests +[console output]:https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/creating-and-highlighting-code-blocks#fenced-code-blocks +[verification steps]:https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/basic-writing-and-formatting-syntax#task-lists +[reference associated issues]:https://github.com/blog/1506-closing-issues-via-pull-requests +[PR#9966]:https://github.com/rapid7/metasploit-framework/pull/9966 +[pre-commit hook]:https://github.com/rapid7/metasploit-framework/blob/master/tools/dev/pre-commit-hook.rb +[API]:https://rapid7.github.io/metasploit-framework/api +[module documentation]:https://docs.metasploit.com/docs/using-metasploit/basics/module-documentation.html +[scripts]:https://github.com/rapid7/metasploit-framework/tree/master/scripts +[RSpec]:http://rspec.info +[Better Specs]:http://www.betterspecs.org/ +[YARD]:http://yardoc.org +[Issues]:https://github.com/rapid7/metasploit-framework/issues +[Metasploit Slack]:https://www.metasploit.com/slack +[#metasploit on Freenode IRC]:http://webchat.freenode.net/?channels=%23metasploit&uio=d4 diff --git a/README.md b/README.md index ceee00dd..24c0c3ef 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md) + # Veilid ## Introduction diff --git a/code_of_conduct.md b/code_of_conduct.md new file mode 100644 index 00000000..d33878e1 --- /dev/null +++ b/code_of_conduct.md @@ -0,0 +1,134 @@ + +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders 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, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[INSERT CONTACT METHOD]. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations + From f4d71457da181278d0e976831eed1e0e0008e259 Mon Sep 17 00:00:00 2001 From: TC Johnson Date: Tue, 1 Aug 2023 21:37:38 -0500 Subject: [PATCH 2/2] Add docs and mod version bumping Added and modified documentation for the contribution process. Added the code of conduct file. Modified bump version's conf to auto create tags and commits. --- .bumpversion.cfg | 3 + CONTRIBUTING.md | 53 ++++------- DEVELOPMENT.md | 217 +++++++++++++++++++++++++++++++++++++++++++ INSTALL.md | 32 +++++++ README.md | 227 ++++----------------------------------------- RELEASING.md | 22 +++-- code_of_conduct.md | 5 +- 7 files changed, 308 insertions(+), 251 deletions(-) create mode 100644 DEVELOPMENT.md create mode 100644 INSTALL.md diff --git a/.bumpversion.cfg b/.bumpversion.cfg index bd23adfd..75f7ef17 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -1,5 +1,8 @@ [bumpversion] current_version = 0.1.7 +tag = True +commit = True +message = 'Version update: {current_version} → {new_version}' [bumpversion:file:veilid-server/Cargo.toml] search = name = "veilid-server" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba7e420f..843c6a9b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,9 @@ # Contributing to Veilid -Before you get started, please review our [Code of Conduct](./CODE_OF_CONDUCT.md). We're here to make things better and we cannot do that by treating each other without respect. +Before you get started, please review our [Code of Conduct](./code_of_conduct.md). We're here to make things better and we cannot do that by treating each other without respect. ## Code Contributions -To begin crafting code to contribution to the Veilid project, first set up a [development environment]. After cloning the project, check out a new local branch and name it in a way that describes the work being done. This is refered to as a topic branch. +To begin crafting code to contribute to the Veilid project, first set up a [development environment]. After cloning the project, check out a new local branch and name it in a way that describes the work being done. This is referred to as a [feature branch]. Some contributions might introduce changes that are incompatible with other existing nodes. In this case it is recommended to also set a [development network]. *NEED TO WRITE* @@ -19,16 +19,16 @@ Keeping the following in mind gives your contribution the best chance of landing #### Merge Requests -* **Do** create a [topic branch] to work on instead of working directly on `main`. This helps to: +* **Do** create a [feature branch] to work on instead of working directly on `main`. This helps to: * Protect the process. * Ensures users are aware of commits on the branch being considered for merge. * Allows for a location for more commits to be offered without mingling with other contributor changes. - * Allows contributors to make progress while a PR is still being reviewed. + * Allows contributors to make progress while a MR is still being reviewed. * **Do** follow the [50/72 rule] for Git commit messages. * **Do** target your merge request to the **main branch**. * **Do** specify a descriptive title to make searching for your merge request easier. * **Do** list [verification steps] so your code is testable. -* **Do** [reference associated issues] in your merge request description. +* **Do** reference associated issues in your merge request description. * **Don't** leave your merge request description blank. * **Don't** abandon your merge request. Being responsive helps us land your code faster. * **Don't** submit unfinished code. @@ -38,29 +38,29 @@ Keeping the following in mind gives your contribution the best chance of landing ## Contributions Without Writing Code There are numerous ways you can contribute to the growth and success of the Veilid project without writing code: - - [submit]() bugs as well as feature/enhancement requests. Letting us know you found a bug, have an idea for a new feature, or see a way we can enhance existing features is just as important and useful as writing the code related to those things. Send us detailed information about your issue or idea: + - Submit bugs as well as feature/enhancement requests. Letting us know you found a bug, have an idea for a new feature, or see a way we can enhance existing features is just as important and useful as writing the code related to those things. Send us detailed information about your issue or idea: - Features/Enhancements: Describe your idea. If you're able to, sketch out a diagram or mock-up. - - Bugs: Please be sure to include the expected behavior, the observed behavior, and steps to reproduce the problem. Please be descriptive about the environment you've installed your node or application into. More information can be found [below](#bug-reports). - - [Help other users with open issues]. Sometimes all an issue needs is a little conversation to clear up a process or misunderstanding. Please keep the [Code of Conduct](./CODE_OF_CONDUCT.md) in mind. + - Bugs: Please be sure to include the expected behavior, the observed behavior, and steps to reproduce the problem. Please be descriptive about the environment you've installed your node or application into. + - [Help other users with open issues]. Sometimes all an issue needs is a little conversation to clear up a process or misunderstanding. Please keep the [Code of Conduct](./code_of_conduct.md) in mind. - Help other contributors test recently submitted merge requests. By pulling down a merge request and testing it, you can help validate new code contributions for stability and quality. - - Report a security or privacy vulnerability. Please let us know if you find ways in which Veilid could handle security and/or privacy in a different or better way. Surely let us know if you find broken or otherwise flawed security and/or privacy functions. You can report these directly to security@veilid.org or by using the form found [on our site]() *NEED TO BUILD* + - Report a security or privacy vulnerability. Please let us know if you find ways in which Veilid could handle security and/or privacy in a different or better way. Surely let us know if you find broken or otherwise flawed security and/or privacy functions. You can report these directly to security@veilid.org. - Add or edit documentation. Documentation is a living and evolving library of knowledge. As such, care, feeding, and even pruning is needed from time to time. If you're a non-native english speaker, you can help by replacing any ambiguous idioms, metaphors, or unclear language that might make our documentation hard to understand. #### Bug Fixes -* **Do** include reproduction steps in the form of verification steps. -* **Do** link to any corresponding [Issues] in the format of `See #1234` in your commit description. +* **Do** include reproduction steps in the form of [verification steps]. +* **Do** link to any corresponding issues in your commit description. ## Bug Reports -Please report vulnerabilities in Veilid directly to security@veilid.org or by using the form found [on our site]() *NEED TO BUILD*. More information about our disclosure policy and Veilid Foundation's approach to coordinated disclosure can be found [on our site](). *NEED TO WRITE* - When reporting Veilid issues: * **Do** write a detailed description of your bug and use a descriptive title. * **Do** include reproduction steps, stack traces, and anything that might help us fix your bug. * **Don't** file duplicate reports. Search open issues for similar bugs before filing a new report. * **Don't** attempt to report issues on a closed PR. New issues should be openned against the `main` branch. +Please report vulnerabilities in Veilid directly to security@veilid.org. + If you're looking for more guidance, talk to other Veilid contributors on the [Veilid Discord]. **Thank you** for taking the few moments to read this far! Together we will build something truely remarkable. @@ -69,29 +69,10 @@ If you're looking for more guidance, talk to other Veilid contributors on the [V This contributor guide is inspired by the contribution guidelines of the [Metasploit Framework](https://github.com/rapid7/metasploit-framework/blob/master/CONTRIBUTING.md) project found on GitHub. -[Code of Conduct]:https://docs.metasploit.com/docs/code-of-conduct.html -[Submit bugs and feature requests]:http://r-7.co/MSF-BUGv1 -[Help fellow users with open issues]:https://github.com/rapid7/metasploit-framework/issues -[help fellow committers test recently submitted merge requests]:https://github.com/rapid7/metasploit-framework/pulls +[Help other users with open issues]:https://gitlab.com/veilid/veilid/-/issues [Report a security vulnerability in Metasploit itself]:https://www.rapid7.com/disclosure.jsp [development environment]:http://r-7.co/MSF-DEV -[proof-of-concept exploits]:https://www.exploit-db.com/search?verified=true&hasapp=true&nomsf=true -[Ruby style guide]:https://github.com/bbatsov/ruby-style-guide -[Rubocop]:https://rubygems.org/search?query=rubocop [50/72 rule]:http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html -[topic branch]:http://git-scm.com/book/en/Git-Branching-Branching-Workflows#Topic-Branches -[draft PR]:https://help.github.com/en/articles/about-pull-requests#draft-pull-requests -[console output]:https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/creating-and-highlighting-code-blocks#fenced-code-blocks -[verification steps]:https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/basic-writing-and-formatting-syntax#task-lists -[reference associated issues]:https://github.com/blog/1506-closing-issues-via-pull-requests -[PR#9966]:https://github.com/rapid7/metasploit-framework/pull/9966 -[pre-commit hook]:https://github.com/rapid7/metasploit-framework/blob/master/tools/dev/pre-commit-hook.rb -[API]:https://rapid7.github.io/metasploit-framework/api -[module documentation]:https://docs.metasploit.com/docs/using-metasploit/basics/module-documentation.html -[scripts]:https://github.com/rapid7/metasploit-framework/tree/master/scripts -[RSpec]:http://rspec.info -[Better Specs]:http://www.betterspecs.org/ -[YARD]:http://yardoc.org -[Issues]:https://github.com/rapid7/metasploit-framework/issues -[Metasploit Slack]:https://www.metasploit.com/slack -[#metasploit on Freenode IRC]:http://webchat.freenode.net/?channels=%23metasploit&uio=d4 +[feature branch]:https://docs.gitlab.com/ee/gitlab-basics/feature_branch_workflow.html +[verification steps]:https://docs.gitlab.com/ee/user/markdown.html#task-lists +[Veilid Discord]:https://discord.gg/DmEGxyA87N diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000..108269db --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,217 @@ +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md) + +# Veilid Development + +## Introduction +This guide covers setting up environments for core, Flutter/Dart, and Python development. See the relevent sections. + +## Obtaining the source code + +```shell +git clone --recurse-submodules git@gitlab.com:veilid/veilid.git +``` + +## Dependencies + +### GNU/Linux + +Development of Veilid on GNU/Linux requires a Debian variant such as Debian +itself, Ubuntu or Mint. Pull requests to support other distributions would be +welcome! + +Running the setup script requires: +* Android SDK and NDK +* Rust + +You may decide to use Android Studio [here](https://developer.android.com/studio) +to maintain your Android dependencies. If so, use the dependency manager +within your IDE. If you plan on using Flutter for Veilid development, the Android Studio +method is highly recommended as you may run into path problems with the 'flutter' +command line without it. If you do so, you may skip to +[Run Veilid setup script](#Run Veilid setup script). + +* build-tools;33.0.1 +* ndk;25.1.8937393 +* cmake;3.22.1 +* platform-tools +* platforms;android-33 + +#### Setup Dependencies using the CLI + + +You can automatically install the prerequisites using this script: + +```shell +./install_linux_prerequisites.sh +``` + +Otherwise, you may choose to use Android `sdkmanager`. Follow the installation +instructions for `sdkmanager` +[here](https://developer.android.com/studio/command-line/sdkmanager), then use +the command line to install the requisite package versions: + +```shell +sdkmanager --install "platform-tools" +sdkmanager --install "platforms;android-33" +sdkmanager --install "build-tools;33.0.1" +sdkmanager --install "ndk;25.1.8937393" +sdkmanager --install "cmake;3.22.1" +``` + +Export environment variables and add the Android SDK platform-tools directory to +your path. + +```shell +cat << EOF >> ~/.profile +export ANDROID_SDK_ROOT= +export ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/25.1.8937393 +export PATH=\$PATH:$ANDROID_SDK_ROOT/platform-tools +EOF +``` + +#### Run Veilid setup script + +Now you may run the Linux setup script to check your development environment and +pull the remaining Rust dependencies: + +```shell +./setup_linux.sh +``` + +#### Run the veilid-flutter setup script (optional) + +If you are developing Flutter applications or the flutter-veilid portion, you should +install Android Studio, and run the flutter setup script: + +```shell +cd veilid-flutter +./setup_flutter.sh +``` + + +### macOS + +Development of Veilid on MacOS is possible on both Intel and ARM hardware. + +Development requires: +* Android Studio +* Xcode, preferably latest version +* Homebrew [here](https://brew.sh) +* Android SDK and NDK +* Rust + +You will need to use Android Studio [here](https://developer.android.com/studio) +to maintain your Android dependencies. Use the SDK Manager in the IDE to install the following packages (use package details view to select version): +* Android SDK Build Tools (33.0.1) +* NDK (Side-by-side) (25.1.8937393) +* Cmake (3.22.1) +* Android SDK 33 +* Android SDK Command Line Tools (latest) (7.0/latest) + +#### Setup command line environment + +Export environment variables and add the Android SDK platform-tools directory to +your path. + +```shell +cat << EOF >> ~/.zshenv +export ANDROID_SDK_ROOT=$HOME/Library/Android/sdk +export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/25.1.8937393 +export PATH=\$PATH:$HOME/Library/Android/sdk/platform-tools +EOF +``` + +#### Run Veilid setup script + +Now you may run the MacOS setup script to check your development environment and +pull the remaining Rust dependencies: + +```shell +./setup_macos.sh +``` + +#### Run the veilid-flutter setup script (optional) + +If you are developing Flutter applications or the flutter-veilid portion, you should +install Android Studio, and run the flutter setup script: + +```shell +cd veilid-flutter +./setup_flutter.sh +``` + +### Windows + +**TODO** + +## Running the Application(s) + +### Veilid Server + +In order to run the `veilid-server` locally: + +```shell +cd ./veilid-server +cargo run +``` + +In order to see what options are available: + +```shell +cargo run -- --help +``` + +#### Configuration + +`veilid-server` has a wealth of configuration options. Further documentation on +the format of the `veilid-server.conf` file may be found [in the project /doc +directory](./doc/config/veilid-server-config.md). + +When running `veilid-server` in a Unix-like environment, the application will +look for its config file under `/etc/veilid-server/`. If the config file is not +found in this location, `veilid-server` will follow the XDG user directory spec +and look in `~/.config/veilid-server`. + +When running under Windows, the `veilid-server.conf` file may be created at +`C:\Users\\AppData\Roaming\Veilid\Veilid\`, and when running under macOS, +at `/Users//Library/Application Support/org.Veilid.Veilid`. + +### Veilid CLI + +In order to connect to your local `veilid-server`: + +```shell +cd ./veilid-cli +cargo run +``` + +Similar to `veilid-server`, you may see CLI options by typing: + +```shell +cargo run -- --help +``` + +## Building the Application + +### Linux Packages + +Veilid server and cli can be built locally using the +[Earthly](https://earthly.dev/) framework. After [installing earthly on your +local machine](https://earthly.dev/get-earthly), you may use the `earthly` cli +to initiate a build: + +```shell +earthly +package-linux +``` + +This will assemble all dependencies and build `.deb` packages for both amd64 and +arm64 platforms. Earthly, built on Docker, caches build layers, so after a +longer first build, subsequent builds should be much quicker. + +During development, you may want to kick off specific build steps. To see a list +of the build steps configured, consult the `Earthfile`, or you may use the +`earthly` cli: + +```shell +earthly ls +``` diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..67f30db5 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,32 @@ +# Install a Veilid Node + +## Server Grade Headless Nodes + +These network support nodes are heavier than the node a user would establish on their phone in the form of a chat or social media application. A cloud based virtual private server (VPS), such as Digital Ocean Droplets or AWS EC2, with high bandwidth, processing resources, and up time availability is cruicial for building the fast, secure, and private routing that Veilid is built to provide. + +### Add the repo to a Debian based system and install a Veilid node + ```shell +wget -O- https://packages.veilid.net/gpg/veilid-packages-key.public | sudo gpg --dearmor -o /usr/share/keyrings/veilid-packages-keyring.gpg +``` +For AMD64 based systems run the following: +```shell +echo "deb [arch=amd64 signed-by=/usr/share/keyrings/veilid-packages-keyring.gpg] https://packages.veilid.net/apt stable main" | sudo tee /etc/apt/sources.list.d/veilid.list 1>/dev/null +``` +For ARM64 based systems, run the following: +```shell +echo "deb [arch=arm64 signed-by=/usr/share/keyrings/veilid-packages-keyring.gpg] https://packages.veilid.net/apt stable main" | sudo tee /etc/apt/sources.list.d/veilid.list 1>/dev/null +``` +For all, run: +```shell +apt update +``` +```shell +apt install veilid-server veilid-cli +``` +### Add the repo to a Fedora based system and install a Veilid node +```shell +yum-config-manager --add-repo https://packages.veilid.net/rpm/veilid-rpm-test-repo.repo +``` +```shell +dnf install veilid-server veilid-cli +``` diff --git a/README.md b/README.md index 24c0c3ef..dc19af3c 100644 --- a/README.md +++ b/README.md @@ -1,216 +1,29 @@ -[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md) +# Welcome to Veilid -# Veilid +- [From Orbit](#from-orbit) +- [Run a Node](#run-a-node) +- [Development](#development) -## Introduction +## From Orbit -## Obtaining the source code +The first matter to address is the question "What is Veilid?" The highest-level description is that Veilid is a peer-to-peer network for easily sharing various kinds of data. -```shell -git clone --recurse-submodules git@gitlab.com:veilid/veilid.git -``` +Veilid is designed with a social dimension in mind, so that each user can have their personal content stored on the network, but also can share that content with other people of their choosing, or with the entire world if they want. -## Dependencies +The primary purpose of the Veilid network is to provide the infrastructure for a specific kind of shared data: social media in various forms. That includes light-weight content such as Twitter's tweets or Mastodon's toots, medium-weight content like images and songs, and heavy-weight content like videos. Meta-content such as personal feeds, replies, private messages, and so forth are also intended to run atop Veilid. -### GNU/Linux +## Run a Node +The easiest way to help grow the Veilid network is to run your own node. Every user of Veilid is a node, but some nodes help the netowrk more than others. These network support nodes are heavier than the node a user would establish on their phone in the form of a chat or social media application. A cloud based virtual private server (VPS), such as Digital Ocean Droplets or AWS EC2, with high bandwidth, processing resources, and up time availability is cruicial for building the fast, secure, and private routing that Veilid is built to provide. -Development of Veilid on GNU/Linux requires a Debian variant such as Debian -itself, Ubuntu or Mint. Pull requests to support other distributions would be -welcome! +To run such a node, establish a Debian or Fedora based VPS and install the veilid-server service. To make this process simple we are hosting package manager repositories for .deb and .rpm packages. See the [installing](./INSTALL.md) guide for more information. + +## Development +If you're inclined to get involved in code and non-code development, please check out the [contributing](./CONTRIBUTING.md) guide. We're striving for this project to be developed in the open and by people for people. Specific areas in which we are looking for help include: -Running the setup script requires: -* Android SDK and NDK * Rust - -You may decide to use Android Studio [here](https://developer.android.com/studio) -to maintain your Android dependencies. If so, use the dependency manager -within your IDE. If you plan on using Flutter for Veilid development, the Android Studio -method is highly recommended as you may run into path problems with the 'flutter' -command line without it. If you do so, you may skip to -[Run Veilid setup script](#Run Veilid setup script). - -* build-tools;33.0.1 -* ndk;25.1.8937393 -* cmake;3.22.1 -* platform-tools -* platforms;android-33 - -#### Setup Dependencies using the CLI - - -You can automatically install the prerequisites using this script: - -```shell -./install_linux_prerequisites.sh -``` - -Otherwise, you may choose to use Android `sdkmanager`. Follow the installation -instructions for `sdkmanager` -[here](https://developer.android.com/studio/command-line/sdkmanager), then use -the command line to install the requisite package versions: - -```shell -sdkmanager --install "platform-tools" -sdkmanager --install "platforms;android-33" -sdkmanager --install "build-tools;33.0.1" -sdkmanager --install "ndk;25.1.8937393" -sdkmanager --install "cmake;3.22.1" -``` - -Export environment variables and add the Android SDK platform-tools directory to -your path. - -```shell -cat << EOF >> ~/.profile -export ANDROID_SDK_ROOT= -export ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/25.1.8937393 -export PATH=\$PATH:$ANDROID_SDK_ROOT/platform-tools -EOF -``` - -#### Run Veilid setup script - -Now you may run the Linux setup script to check your development environment and -pull the remaining Rust dependencies: - -```shell -./setup_linux.sh -``` - -#### Run the veilid-flutter setup script (optional) - -If you are developing Flutter applications or the flutter-veilid portion, you should -install Android Studio, and run the flutter setup script: - -```shell -cd veilid-flutter -./setup_flutter.sh -``` - - -### macOS - -Development of Veilid on MacOS is possible on both Intel and ARM hardware. - -Development requires: -* Android Studio -* Xcode, preferably latest version -* Homebrew [here](https://brew.sh) -* Android SDK and NDK -* Rust - -You will need to use Android Studio [here](https://developer.android.com/studio) -to maintain your Android dependencies. Use the SDK Manager in the IDE to install the following packages (use package details view to select version): -* Android SDK Build Tools (33.0.1) -* NDK (Side-by-side) (25.1.8937393) -* Cmake (3.22.1) -* Android SDK 33 -* Android SDK Command Line Tools (latest) (7.0/latest) - -#### Setup command line environment - -Export environment variables and add the Android SDK platform-tools directory to -your path. - -```shell -cat << EOF >> ~/.zshenv -export ANDROID_SDK_ROOT=$HOME/Library/Android/sdk -export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/25.1.8937393 -export PATH=\$PATH:$HOME/Library/Android/sdk/platform-tools -EOF -``` - -#### Run Veilid setup script - -Now you may run the MacOS setup script to check your development environment and -pull the remaining Rust dependencies: - -```shell -./setup_macos.sh -``` - -#### Run the veilid-flutter setup script (optional) - -If you are developing Flutter applications or the flutter-veilid portion, you should -install Android Studio, and run the flutter setup script: - -```shell -cd veilid-flutter -./setup_flutter.sh -``` - -### Windows - -**TODO** - -## Running the Application(s) - -### Veilid Server - -In order to run the `veilid-server` locally: - -```shell -cd ./veilid-server -cargo run -``` - -In order to see what options are available: - -```shell -cargo run -- --help -``` - -#### Configuration - -`veilid-server` has a wealth of configuration options. Further documentation on -the format of the `veilid-server.conf` file may be found [in the project /doc -directory](./doc/config/veilid-server-config.md). - -When running `veilid-server` in a Unix-like environment, the application will -look for its config file under `/etc/veilid-server/`. If the config file is not -found in this location, `veilid-server` will follow the XDG user directory spec -and look in `~/.config/veilid-server`. - -When running under Windows, the `veilid-server.conf` file may be created at -`C:\Users\\AppData\Roaming\Veilid\Veilid\`, and when running under macOS, -at `/Users//Library/Application Support/org.Veilid.Veilid`. - -### Veilid CLI - -In order to connect to your local `veilid-server`: - -```shell -cd ./veilid-cli -cargo run -``` - -Similar to `veilid-server`, you may see CLI options by typing: - -```shell -cargo run -- --help -``` - -## Building the Application - -### Linux Packages - -Veilid server and cli can be built locally using the -[Earthly](https://earthly.dev/) framework. After [installing earthly on your -local machine](https://earthly.dev/get-earthly), you may use the `earthly` cli -to initiate a build: - -```shell -earthly +package-linux -``` - -This will assemble all dependencies and build `.deb` packages for both amd64 and -arm64 platforms. Earthly, built on Docker, caches build layers, so after a -longer first build, subsequent builds should be much quicker. - -During development, you may want to kick off specific build steps. To see a list -of the build steps configured, consult the `Earthfile`, or you may use the -`earthly` cli: - -```shell -earthly ls -``` +* Flutter/Dart +* Python +* Gitlab DevOps and CI/CD +* Documentation +* Security reviews +* Linux packaging \ No newline at end of file diff --git a/RELEASING.md b/RELEASING.md index f866b5ae..4b51375c 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -7,9 +7,17 @@ Veilid is a monorepo consisting of several projects: ## Release Mechanism -Releases happen via a CI/CD pipeline. Builds and tests are automatic and must succeed before a release is triggered. Releases happen if a successful build pipeline off of the `main` branch runs, followed by test pipeline, followed by package pipeline. - -A new tag is calculated for each released artifact in the format 'name-v0.1.0', where the name is the pipeline name (veilid-server-deb-v0.0.0) for example. If the version number on the resulting output package artifact has changed from the most recent tag for that artifact, it is published. If publication is successful, the repository is tagged with the new tag. Multiple releases and tags can happen per pipeline run, if multiple version numbers are bumped in the same commit. +Releases happen via a CI/CD pipeline. The release process flows as follows: +1. Maintainer responds to a merge request (MR): + a. Evaluate the MR's adherence to the published requirements and if automatic tests passed. + b. (Optional) Perform the merge in a local dev environment if testing is required beyond the standard Earthly tests. + c. If everything checks out, MR meets the published requirements, and tests passed, execute the merge functions in the Gitlab UI. +2. Maintainer performs version bump: + a. Update your local copy of `main` to mirror the newly merged version + b. Execute the bumpversion.py process. + c. Push your local 'main' to the upstream origin 'main' `git push` + d. Push the new tag to the upstream origin `git push "tag name made in step 2d"` + e. Ensure the package/release/distribute pipeline autostarted in the Gitlab UI Tags serve as a historical record of what repo versions were successfully released at which version numbers. @@ -54,19 +62,19 @@ Occasionally a release will happen that needs to be reverted. This is done manua - [x] __veilid-server__ DEB package [**Tag**: `veilid-server-deb-v0.0.0`] > The Veilid headless node binary in the following formats: > * Standalone Debian/Ubuntu DEB file as a 'release file' on the `veilid` GitLab repository - > * Pushed to APT repository at https://packages.veilid.com + > * Pushed to APT repository at https://packages.veilid.net - [x] __veilid-server__ RPM package [**Tag**: `veilid-server-rpm-v0.0.0`] > The Veilid headless node binary in the following formats: > * Standalone RedHat/CentOS RPM file as a 'release file' on the `veilid` GitLab repository - > * Pushed to Yum repository at https://packages.veilid.com + > * Pushed to Yum repository at https://packages.veilid.net - [x] __veilid-cli__ DEB package [**Tag**: `veilid-cli-deb-v0.0.0`] > The Veilid headless node administrator control binary in the following formats: > * Standalone Debian/Ubuntu DEB file as a 'release file' on the `veilid` GitLab repository - > * Pushed to APT repository at https://packages.veilid.com + > * Pushed to APT repository at https://packages.veilid.net - [x] __veilid-cli__ RPM package [**Tag**: `veilid-cli-rpm-v0.0.0`] > The Veilid headless node administrator control binary in the following formats: > * Standalone RedHat/CentOS RPM file as a 'release file' on the `veilid` GitLab repository - > * Pushed to Yum repository at https://packages.veilid.com + > * Pushed to Yum repository at https://packages.veilid.net ### Version Numbering: diff --git a/code_of_conduct.md b/code_of_conduct.md index d33878e1..c039824b 100644 --- a/code_of_conduct.md +++ b/code_of_conduct.md @@ -61,7 +61,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -[INSERT CONTACT METHOD]. +[security@veilid.org](security@veilid.org). All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the @@ -132,3 +132,6 @@ For answers to common questions about this code of conduct, see the FAQ at [FAQ]: https://www.contributor-covenant.org/faq [translations]: https://www.contributor-covenant.org/translations +## Revisions +Veilid Foundation, Inc reserves the right to make revisions to this document +to ensure its continued alignment with our ideals. \ No newline at end of file