Git-Mirrors/veilid-dot-com
1
0
Fork 0
mirror of https://gitlab.com/veilid/veilid-dot-com.git synced 2024-07-01 16:41:24 +00:00
Code Issues Packages Projects Releases Wiki Activity
0368ca5870
veilid-dot-com/CONTRIBUTING.md
Alice Rhodes ceff01aa32 Moving site
2023-08-15 15:25:21 -04:00

5.9 KiB
Raw Blame History

Contributing to Veilid

Before you get started, please review our Code of Conduct. We're here to make things better and we cannot do that by treating each other without respect.

Code Contributions

Tech Overview

veilid.com is a flat-file website hosted on Netlify and generated using cecil.app. Cecil is powered by PHP and Twig templates with the content in markdown files.

The site theme uses Bootstrap and Sass; jQuery is available as more content is added we may need more UI features.

The Cecil documentation is pretty great but here's a quick start guide:

Local Development

  1. Install PHP 7.4 or higher
  2. Download and install Cecil
  3. Fork and/or clone the website repository at git@gitlab.com:veilid-tc-hacking/veilid-dot-com.git
  4. In the project directory, run cecil serve to run the site locally on port 8000
  5. Open http://localhost:8000/ in your browser to view it

As you make changes to the code, Cecil will reload the website for you so you can see your changes as you work.

  • pages contains the content for the website in markdown
  • files in static get served off of / in the site URL
  • the site theme is in themes/veilid
    • the Sass files are in themes/veilid/assets/scss and get compiled into CSS for you by Cecil — please do not edit the CSS files directly
    • themes/veilid/static get added to the static content directory
    • themes/veilid/layouts has all the twig template files
    • note that not all twig templates in the theme directory are used on the site

Code Contribution Do's & Don'ts:

Keeping the following in mind gives your contribution the best chance of landing!

Merge Requests

  • 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 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.
  • 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.
  • 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 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.
  • 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 your commit description.

Bug Reports

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 truly remarkable.

This contributor guide is inspired by the contribution guidelines of the Metasploit Framework project found on GitHub.