Contributing

Local Development Requirements

1. First, install the following on your environment:
   • make
   • go (>=1.24)
   • nodejs(>=20.0.0)
   • npm (>=10.9.0)
2. Run make setup to get things setup and installed.

Release Strategy

This repo has a specific release flow that goes something like this:

1. A dev/vX.X.X branch is created from main. These branches do not produce releases and may sometimes be broken and non-functioning.
2. Changes on the dev/vX.X.X branch should be done through pull requests on a feature branch named such as my-new-feature
3. Once a dev/vX.X.X branch is ready, deployable, tested, and reasonably stable - it can be promoted to a beta/vX.X.X branch (with the same version number).
4. A beta/vX.X.X branch will automatically create beta releases with binaries on the release page. Any bug fixes or functional changes needed for a beta release should go through another dev/vX.X.X branch and promotion process. Non-functional changes such as readme/config/workflow changes can be done via a pull request to beta/vX.X.X from a feature branch such as update-workflow
5. The same process and rules should occur for stable/vX.X.X branches once stable has been reached -- requiring bugfixes to propagate from dev/vX.X.X to reach stable via promote to stable workflow.

Note

One big difference in the release process for stable/vX.X.X and beta/vX.X.X branches will be the release cadence. The releases for stable/vX.X.X branches should be separated by weeks and may skip minor versions. For example, a beta/v1.1.1 release may be superseded by a beta/v1.1.2 release -- and consequently, a stable/v1.1.1 may never get promoted because a newer more "stable" version stable/v1.1.2 exists. Furthermore, initial minor versions (eg stable/vX.X.0) are unlikely to make it to stable because there will likely be additional minor version updates that occur within the "weeks" wait period between stable releases.

Github Workflow For Releases

Release automation happens via GitHub actions. These actions happen in these forms:

1. Automated tests
   • Every branch has unit tests that ensure code compiles and passes basic tests
   • Every branch has linting -- meaning automatic code checks to ensure standards are being met.
   • Pull Requests and releases must pass "playwright test". These are integration tests that test functionality in the UI automatically -- such as creating users, viewing files, moving files, etc.
2. Automated releases
   • stable/vX.X.X and beta/vX.X.X branches automatically generate releases, which are found on Git Hub, these releases automatically get binary files added based on goreleaser configuration.
   • main branch does a simple latest docker image update -- which will build and tag the latest docker image using whatever is the latest beta tag (for right now, there are no stable tags).

Contributing as an unofficial contributor

If you would like to contribute, please open a pull request against main branch, and an official contributor may comment and change the base to a current dev/vX.X.X branch in progress to add the feature.

A PR is required to have:

• A clear description of why it was opened.
• A short title that best describes the change.
• Must pass unit and integration tests, which can be run checked locally prior to opening a PR.
• Any additional details for functionality not covered by tests.

Unit tests should be updated to pass before merging. So, the best way to handle this is to create a fork and test your changes there, then open a pull request against this repo. You can also create a draft pull request if it is not fully ready.

Note

You can run local linting and unit tests locally via make commands. You may need to first run make setup to install dev tools, then make check-all to run unit tests and linting.

You can run make run to compile and run locally. This will use the backend/test_config.yaml (which is created during make setup), which you can tweak and update at any time for testing, changes will not get committed to git.\

Important local building tips:

• make check-all simulates the regular tests in Git Hub, doing unit tests and lining.
• make test-playwright simulates the integration tests needed for PRs.
• make run to build and run locally. Also, updates generated documentation.
• if building on Windows, you will need to do the build processes manually -- for example, compiling the frontend via npm run build-windows, then running the backend manually via cd backend/ && go run . -c test_config.yaml

Contributing as an official contributor

Official contributors do not need to fork the branch because they have access to the repo. So, an official contributor would follow all release strategies, answer GitHub questions, and handle incoming pull requests from forks.

Contributing without code changes

You may want to contribute, but don't have the means or time to submit code pull requests. That's ok, you can still contribute by engaging on GitHub via GitHub issues and discussions.

Please don't hesitate to open an issue for any ideas you have, but don't want to open a pull request directly.

Updating Translations

There are two situations where translations will need to be updated:

1. If existing translations can be improved, or certain languages are missing translations
   • In this situation, a contributor would update the language files with the corresponding language attribute. By updating these files, they should automatically update the UI for those languages.
   • You can identify the language fields that need updating by (preferably) finding and replacing the existing text you want. If you are having trouble locating it, you can navigate to the corresponding *.vue file to update it in frontend/src/
2. A new addition you are adding has raw text somewhere in the component or no matching field. You will need to define a new field in the en.json (which is the master language file), and then cd into frontend set your DEEPL API token (will need free account created to get API token), and run npm run i18n:sync which will auto-generate the other language fields. You may then modify as needed.