Skip to content

Latest commit

 

History

History
183 lines (118 loc) · 9.27 KB

CONTRIBUTING.md

File metadata and controls

183 lines (118 loc) · 9.27 KB
Raw

Contributing

We'd love you to contribute to dyrector.io platform. We want contribution to dyrector.io to be fun, enjoyable, and educational for anyone and everyone. All contributions are welcome, including issues, new docs as well as updates and tweaks, blog posts, workshops, and more.

Code of Conduct

Help us keep dyrector.io open and inclusive. Please read and follow our Code of Conduct.

How to Start?

If you're worried or don’t know where to start, check out our next section explaining what kind of help we could use and where you can become involved. You can reach out with questions to our Discord server or @dyrectorio on Twitter.

Development

  1. Run make upd in the repo's root folder.
  • Save your DATABASE_URL=<connection_string> environment variable for later.
  1. Go to the web/crux directory: cd web/crux
  2. Install dependencies npm ci
  3. Copy the env.example file as .env cp .env.example .env
  • Paste DATABASE_URL=<connection_string> variable from step 1 to .env
  1. On Linux:
  • Uncomment the DNS_DEFAULT_RESULT_ORDER=ipv4first line in the .env file
  • Change the CRUX_AGENT_ADDRESS variable's value to 172.17.0.1:5000
  1. On Mac / Windows you may have to edit your OS's hosts file to be sure the host.docker.internal domain resolves to docker's bridge network.
  • Alternatively, you can use your machine's LAN IP.
  1. Deploy the database with npm run prisma:migrate
  2. Start the backend in development mode with npm start
  3. Go to the web/crux-ui directory: cd web/crux-ui
  4. Install dependencies npm ci
  5. Copy the env.example file as .env cp .env.example .env
  6. Start the frontend in development mode with npm start but in a different terminal
  7. After you navigate to localhost:8000 (this is the default Traefik port) you will see a Login screen
  8. Register an account with whatever e-mail address you see fit (doesn't have to be a valid one)
  9. Navigate to localhost:4436 where you will find your mail as all outgoing e-mails will land here
  10. Open your e-mail message and using the link inside you can activate your account
  11. Fruitful contributing! 🎬

Read more about the CLI in the documentation.

Testing

Unit tests:

  • In the web/crux or web/crux-ui folder respectively:
  1. Run npm ci.
  2. Start the tests with npm run test.

End-to-end tests:

  1. Run make upd in the repo's root folder.
  • Save your DATABASE_URL=<connection_string> environment variable for later.
  1. Go to the web/crux directory: cd web/crux
  2. Install dependencies npm ci
  3. Build the package npm run build
  4. Copy the env.example file as .env cp .env.example .env
  5. On Linux:
  • Uncomment the DNS_DEFAULT_RESULT_ORDER=ipv4first line in the .env file
  • Change the CRUX_AGENT_ADDRESS variable's value to 172.17.0.1:5000
  1. On Mac / Windows you may have to edit your OS's hosts file to be sure the host.docker.internal domain resolves to docker's bridge network.
  • Alternatively you can use your machine's LAN IP.
  1. Deploy the database with npm run prisma:migrate
  2. Start the backend in production mode with npm run start:prod
  3. Repeat steps 3-5 in the web/crux-ui folder in a different terminal
  4. Start the frontend in production mode with npm run start:prod
  5. Be sure that chromium is installed on your system
  • You may have to run npx playwright install-deps
  • More info: https://playwright.dev/docs/intro
  • Additional note: On some systems like Manjaro, npx playwright install-deps does not work (warning message: "your OS is not officially supported by Playwright"). In this case, you can run npm init playwright@latest and when prompted with the question "Install Playwright operating system dependencies", choose "No". After that, for Manjaro, you need to separately install Playwright from the AUR repository with the package manager and everything works just fine.
  1. In a different terminal go to the web/crux-ui folder and run npm run test:e2e
  • If you want to run a specific test file from the web/crux-ui/e2e folder you can do it with DEBUG=1 npx playwright test <file_name>
  • If you want to open the inspector to see the tests running you can do it with PWDEBUG=1 npx playwright test <file_name>

Changelog

We use various tools to draft our release, changelogs are generated and versions are bumped. It's in the release target of the root folder's Makefile.

make release

Git branching strategy

We have two persistent branches: main, develop. PRs are going into develop. The develop branch is always fast-forward mergable to main. PR titles must follow the conventional commit guidelines.

Release: a release commit is made to develop, package versions are bumped, develop is fast-forward merged into main. Hotfix: in rare occassions, a hotfix/** branch is created from main and the PR targets the main branch, develop must be rebased to main -- using rebase-onto.

Submit a Pull Request

Branch naming convention is as following

TYPE/DESCRIPTION-DESCRIPTION

When TYPE can be:

  • chore/ - Formatting, style, repository structure, or version updates that do not affect functionality.
  • cicd/ - Changes related to the CI/CD system, such as build script or configuration updates.
  • doc/ - Changes focused on documentation updates, including README files, documentation files, or code comments.
  • feat/ - Implementation of new features or functionality.
  • fix/ - Resolution of bugs or issues in the codebase.
  • hotfix/ - Urgent bug fixes on the main branch to address critical issues.
  • refactor/ - Code changes to improve structure, readability, or maintainability.
  • test/ - Changes related to testing, including adding or modifying test cases or improving the testing infrastructure.

All PRs must include a commit message with the changes described.

dyrector.io is following Conventional Commits, the commit messages should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The commit contains the following structural elements, to communicate intent to the consumers of dyrector.io library:

  1. fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
  2. feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
  3. BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
  4. types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the the Angular convention) recommends build:, chore:, ci:, doc:, style:, refactor:, test:, and others.
  5. footers other than BREAKING CHANGE: <description> may be provided and follow a convention similar to git trailer format.

More info: Conventional Commits.

Security & Privacy

Security and privacy are extremely important to dyrector.io's core team, its independent developers, and users alike. Make sure to follow the best industry standards and practices.

Dependencies

Please avoid introducing new dependencies to dyrector.io without consulting the team. New dependencies can be very helpful but also introduce new security and privacy issues, complexity, and impact total docker image size.

Adding a new dependency should provide meaningful value to the product with minimum possible risk.

Other Ways to Help

Pull requests are great, but there are many other areas where you can help dyrector.io.

Sending Feedbacks & Reporting Bugs

Sending feedback is a great way for us to understand your different use cases of dyrector.io better. If you had any issues, bugs, or want to share about your experience, feel free to do so on our GitHub issues page or at our Discord server.

Submitting New Ideas

If you think dyrector.io could use a new feature, please open an issue on our GitHub repository, stating as much information as you can think of your new idea and it's implications. We'd also use this issue to gather more information, get more feedback from the community, and have a proper discussion about the new feature.

Improving Documentation

Submitting documentation updates, enhancements, designs, or bug fixes. Spelling or grammar fixes will be very much appreciated.

Commit signatures

Submitting pull requests require all commits to be signed with a GPG signature. Refer to the GitHub documentation to setup GPG signing.