Developer Guidelines
To begin, you need to clone or fork the repository that contains the code you want to work with. Here's how you can do it:
- Open a web browser and navigate to the repository you want to clone or fork on GitHub.
- Click on the "Clone" or "Fork" button to create a local copy of the repository on your computer. Follow the instructions provided by the code hosting platform to clone or fork the repository using either HTTPS or SSH.
Once you have cloned or forked the repository, navigate to the PathKit folder where the PathKit code and dependencies are located. Here's how you can do it:
- Open a command-line interface (CLI) or terminal window on your computer.
- Change the current directory to the location where you have cloned or forked the repository. For example, if you cloned the repository to your desktop, you can use the cd command to navigate to the desktop folder:
cd Desktop/PathKit
Now that you are inside the PathKit folder which contains package.json, you can run npm install to install the dependencies required for the PathKit code. Here's how you can do it:
- If you do not have Node.js, you may need to install it to run npm: https://nodejs.org/en
- In the CLI or terminal window, make sure you are in the PathKit folder of the cloned or forked repository.
- Run the
npm installcommand to install the dependencies listed in thepackage.jsonfile of the PathKit code. This command will download and install the required dependencies from the npm registry. If this does not work, make sure you have installed the latest version of Node.js and added it to your PATH. It is also recommended to runnpm installvia command line rather than an IDE helper tool. - Wait for the installation to complete. You will see progress messages in the CLI or terminal window indicating the installation progress.
- Once the installation is finished, you should see a node_modules folder created in the PathKit folder, containing the installed dependencies.
While you are inside the PathKit folder which contains package.json, you can run npm run build to install the dependencies required for the PathKit code. Here's how you can do it:
- If you do not have Node.js, you may need to install it to run npm: https://nodejs.org/en
- In the CLI or terminal window, make sure you are in the PathKit folder of the cloned or forked repository.
- Run the
npm run buildcommand to install the distribution files listed in the PathKit code. This command will download and install the required dependencies from the npm registry. If this does not work, make sure you have installed the latest version of Node.js and added it to your PATH. It is also recommended to runnpm run buildvia command line rather than an IDE helper tool. - Wait for the installation to complete. You will see progress messages in the CLI or terminal window indicating the installation progress.
- Once the installation is finished, you should see a dist folder created in the PathKit folder, containing the installed distribution files.
That's it! You have successfully cloned or forked a repository, and run npm install and npm run build under the PathKit folder to get the dependencies and distribution. You can now continue with other steps or tasks related to the codebase, such as building, testing, or running UI application. If you would like to run PathKit locally beyond the source code for a UI interface follow the steps below to build a local dev copy. Remember to always refer to the documentation provided by the repository or project for specific instructions and requirements.
Tauri makes this easy for you! Before going forward to build the software you will need to get the dependencies for Tauri, which you can find here: https://tauri.app/v1/guides/getting-started/prerequisites. After that you can just navigate to you your command line under the main build folder and type npm run tauri build. This step should be done first to ensure a proper build with no issues, but once this is run once, your testing interface can be run with npm run tauri dev.
If you installed alpha release, you may need to also go through some debugging steps listed here, as PathKit relies on your local storage to run. Our pre-release did not guarantee consistent storage into the final build, and the database went through significant changes.
For security reasons we do not provide .env files for the search bar feature. You may consider connecting this to your private server instance, or reaching out to the PathKit team for changes to the server side information.
This is done with a CLI pipeline using Github actions. First you will need to manually update the version control following version guidelines in both package.json, package-lock.json, Cargo.toml and tauri.config.json. Save and merge this to the main branch.
Then you can easily create a release under GitHub actions by selecting the release pipeline. This process may take a while.
This will create a draft of the release, which you can see under the releases page. Currently there is a bug which will create 2 drafts, one which logs our changes, and the other which holds our downloads. We will fix this soon! Go to the draft with downloads and select edit.
At the top you will need to create a new tag which is named after the version released:
Select create new tag on publish for the tag you type in. Mark as latest release and select publish release.
Once you have published the release, go back to the repro and navigate to website>src>hooks>useDownload.ts. Update the links used in the following convention:
https://github.com/LeeJMorel/PathKit/releases/download/tag of latest release/if the type of download has a release number, update that as well to match.
The project follows the following directory structure:
This directory contains files related to GitHub configuration, such as issue templates, pull request templates, and code owners.
This directory contains documentation-related files, including assets, organization markdown (ORG.md) file, and weekly reports of the development process.
This directory contains the entire front end of the application code, including frontend components, assets, and store hooks. To access the UI (view) code navigate to the src folder. From here you will see the main instance of our application, App.tsx. You will also see these folders:
- /assets: This directory contains assets specific to the UI, such as CSS files, images, etc.
- /components: This directory contains UI components that make up our application.
- /sheets: This directory contains UI components that only exist in the center column, known as Sheets
- /views: This directory contains UI components that make up each column view, to then fill with the appropriate components such as cards, sheets, or modules.
- /cards: This directory contains UI components that only exist in the left-hand column, known as Cards
- /menus: This directory contains UI components that only exist in the pop-up menu
- /modules: This directory contains UI components that only exist in the right-hand column, known as Modules
- /others... There are more component folders for everything from menus to buttons used to build the application. Each folder has its own scss style sheet, creating consistent style throughout the application.
- /hooks: This directory contains custom hooks used in the UI code.
- /styles: This directory contains colors and color themes used in the UI scss code.
To access the backend (model) navigate to the tauri-src folder. From here you will see the main instance of our database and rust container that makes our executable. You will also see these folders:
- /icons: This directory contains the executable application icons
- /src: This directory contains the main executable and database creation files.
To access the awesome website navigate to the website folder. Its a simple one page app to host our latest releases.
To access the tests navigate to the test folder.
The main documentation file that provides information about the project, its purpose, usage instructions, and other relevant details.
There are two main ways in which testing takes place: by running frontend tests and backend tests, as specified below.
To run frontend tests, navigate to the main directory and run npm run test, which enters testing watch mode by default. It will run tests on any files that are edited. To run one pass of tests, run npm run test run. This is known to cause difficult test skipping issues, so we have a workaround to run npm run test run -- -t e if you want a full pass of the testing suite.
If you want to run a subsection of all tests, change the "e" after the -t flag to a string which the test paths will be matched against.
To run backend tests, navigate to the src-tauri/ subdirectory and run cargo test, which will run one pass of all unit tests.
Note: there is currently no backend testing need, as the backend logic is hosted inside the frontend components through a wrapper plugin. Yeah, that's confusing, but all the logic that needs to be tested should be tested in the frontend or relevant components. This information is kept here in case any rust components are contributed in the future
To add a new test, first navigate to the main directory and make a new file. Each test file should cover exactly one react component. The naming convention is as follows: Component.tsx => Component.test.tsx See tests/Placeholder.test.tsx for a good template test file. For help with writing certain test behaviors, see the documentation for react-testing-library and vitest
Rust unit tests are done in the same file they are testing. Declare a module at the bottom of the file named “tests” and add the #[cfg(test)] macro above the module. Inside, a new test can be defined with a function that has the #[test] macro above it. See the Rust book’s testing guide for more information about syntax