Begginer's guide ================ :Author: Kamil Zdancewicz :Date: 24-02-2026 This page is a starting point for anyone's journey with the BigOS project. Containing advice from hints for basic procedures *(e.g. What should be in a PR?)* to links and FAQ. -------------------- Repository structure -------------------- The *CMake* directory contains CMake config files and toolchain for the `RISC-V `_ architecture. The *external* directory contains third-party dependencies, we try to use as little external code as possible, so if external code is required, its inclusion must be clearly justified. The *scripts* directory contains useful scripts to check code cleanliness and maintain style consistency. The *docs* directory contains the project documentation, rules and additional information to help You navigate and collaborate effectively. Lastly, the *src* and *include* directories – where **95%** of Your work will take place. --------------------- Pull request workflow --------------------- A pull request *should* concern a single, specific functionality, in specific cases a bundle of functionalities in a single PR may be requested but again – it needs to be justified! Commit names and descriptions should be substantive *(no "Minor changes")*. This also concerns the pull request Assignees, labels, etc. ~~~~~~~~~~~~~~~~~~ Opening a draft PR ~~~~~~~~~~~~~~~~~~ Unless your implementation is ready, consider opening the pull request as a draft first. This signals to the team that: 1. Someone is working on the topic 2. It's **not** finished yet 3. With clear documentation of progress and plans, it allows for others e.g. with dependencies on your work to predict when it will be finished ~~~~~~~~~~~~~~~~~~~~~~ Opening a pull request ~~~~~~~~~~~~~~~~~~~~~~ After finishing the implementation ensure the following: * Verify that the implementation works, try to test it as best you can * The documentation covers everything that was changed * All GitHub actions pass * Clean up commits if necessary If everything is completed You're free to request a review. ~~~~~~~~~~~~~~~~~~~~~ Reviews and Revisions ~~~~~~~~~~~~~~~~~~~~~ According to :doc:`the contributing rules `, at least one reviewer needs to approve a pull request before merging it to the main repository. If a reviewer requests changes, address all comments by either explaining your implementation or making the necessary adjustments. The comments may concern code comprehensibility or non-critical details, if something is unclear, try to provide an explanation to others. Even if the pull request is accepted, make sure all conversations are resolved before merging. ~~~~~~~ Merging ~~~~~~~ After the pull request has been approved and all conversations are resolved, You can merge the changes into the main branch. If merge conflicts occur, consult the team members responsible for the affected files. If You're working with branches, delete the branch after merging, unless it is intended for ongoing work. ----------------------- Reviewing Pull Requests ----------------------- Careful review of other's code is just as important as writing Your own. As a reviewer, follow these guidelines: * Familiarize Yourself with the context first * Ensure the implementation works logically * Check for clarity, readability, and maintainability * Look for potential bugs, edge cases, or missing error handling * Provide constructive feedback * Ask questions if something is unclear * If changes are needed, clearly describe what should be improved * Respond to the author’s updates and verify fixes * Approve the PR if it meets quality standards ----------- Discussions ----------- Don't be afraid to discuss more freely on the Discord server if you have access. Many useful resources were already found and plans have been made. Until they get added to the docs, that's where You'll find them.