diff --git a/docs/contributing/adding_content.md b/docs/contributing/adding_content.md index 7d85cbb1..2caa97d1 100644 --- a/docs/contributing/adding_content.md +++ b/docs/contributing/adding_content.md @@ -52,14 +52,15 @@ $ git checkout -b jjjermiah/adding-getting-started-page If you already have a named branch, you can switch to it with the following command: ```console -git switch jjjermiah/adding-getting-started-page +git switch +$ git switch jjjermiah/adding-getting-started-page ``` ### 2. Add your new content to the `docs` directory ??? question "How do I know where to create my file?" - This will create an empty Markdown file called `my_new_page.md` in the `docs/onboarding` directory. + The command below will create an empty Markdown file called `my_new_page.md` in the `docs/onboarding` directory. The relative path to the `docs` directory, will be the link to your new page.
i.e the link to your new page will be `/handbook/onboarding/my_new_page/` @@ -71,27 +72,46 @@ $ touch docs/onboarding/my_new_page.md You should now see a new file at `docs/onboarding/my_new_page.md`. ``` -To learn more about how to actually write content, see the [HandBook MkDocs Page][mkdocs] and +To learn more about how to actually write content, see the [Handbook MkDocs Page][mkdocs] and [Handbook Markdown page][markdown]. ### 3. Preview your changes The following is a [`pixi task`](https://pixi.sh/latest/features/advanced_tasks/) -that will start a local server and preview the documentation at `http://localhost:8000`. +that will start a local server and preview the documentation at `http://localhost:8001` (aka `http://127.0.0.1:8001`). ```console $ pixi run serve INFO - Building documentation... INFO - Cleaning site directory ... -INFO - [08:55:05] Serving on http://127.0.0.1:8000/handbook/ +INFO - [08:55:05] Serving on http://127.0.0.1:8001/handbook/ ``` -You should see your changes appear at `http://127.0.0.1:8000/handbook/onboarding/my_new_page/` +You should see your changes appear at `http://127.0.0.1:8001/handbook/onboarding/my_new_page/` + +!!! tip + You can set the handbook website to automatically open in your default + browser by using the `-o` flag: + + ```sh + pixi run serve -o + ``` + +!!! note "About the port number" + By default, we host the local site on port `8001` because it is more likely + to be unused and available for the local server to use. In the case that you + would like to manually specify a different port (e.g. if it's in use by + something else), you can use the `-a` flag after `pixi run serve`. + + For example, to run on port `1234`: + ```sh + pixi run serve -a localhost:1234 + ``` ### 4. Commit and push your changes to your branch -```console +```sh git add . git commit -m "Add new getting started page" git push --set-upstream origin jjjermiah/adding-getting-started-page diff --git a/docs/contributing/conventional_commits.md b/docs/contributing/conventional_commits.md index 6596b873..882a6cbd 100644 --- a/docs/contributing/conventional_commits.md +++ b/docs/contributing/conventional_commits.md @@ -1,6 +1,6 @@ -# [Convential Commits](#convential-commits) +# [Conventional Commits](#conventional-commits) -We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages. This helps us automate our release process and keep our commit history clean. +We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages. This helps us automate our release process and keep our commit history clean. This style is mandatory for [merging pull requests][modify-the-commit-message-as-needed] on the handbook, but are recommended for all commits. @@ -30,14 +30,13 @@ The `` of the header is optional and provides context for where the chang - `perf`: A code change that improves performance. - `test`: Changes to the test framework. - `build`: Changes to the build process or tools. -- `ci`: Changes to CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) -- `chore`: Other changes that don't modify src or test files +- `ci`: Changes to CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs). +- `chore`: Other changes that don't modify src or test files. Other types may be defined per project, but these are the most common. - ## Sources 1. [Angular Commit Format Reference Sheet - Brian Clements](https://gist.github.com/brianclements/841ea7bffdb01346392c) 2. [Origin of Angular Commit Style - AngularJS Git Commit Guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits) -3. [Py-Pkgs tutorial - Automatic version bumping using Angular Commit Style](https://py-pkgs.org/en/latest/development/commit-guidelines.html) \ No newline at end of file +3. [Py-Pkgs tutorial - Automatic version bumping using Angular Commit Style](https://py-pkgs.org/en/latest/development/commit-guidelines.html) diff --git a/docs/contributing/merging_pr.md b/docs/contributing/merging_pr.md index 07183221..0bf8cd0b 100644 --- a/docs/contributing/merging_pr.md +++ b/docs/contributing/merging_pr.md @@ -27,7 +27,7 @@ This is called a **Merge Commit**.
Merge commit example
-We will be using the **Squash Merge** strategy for merging pull requests. +We use the **Squash Merge** strategy for merging pull requests to the lab handbook. Squash merges are a way to combine multiple commits into a single commit. Instead of seeing all the author's individual commits in the main branch's @@ -68,7 +68,7 @@ Feel free to modify the body of the commit message to include only the relevant !!! note - Only the PR Title needs to follow the [Conventional Commits][convential-commits] specification. + Only the PR Title needs to follow the [Conventional Commits](conventional_commits.md) specification. The commit message body can be modified to include any relevant commits. ![better_pr](images/better_pr_body.png){: style="height:100%;width:100%"} @@ -76,7 +76,12 @@ Feel free to modify the body of the commit message to include only the relevant ### Verify GitHub Pages Deployment After merging the pull request, the changes will be deployed to GitHub Pages. -Check the website at `https://bhklab.github.io/handbook/` to verify that the changes are correct. +Check the website at [`https://bhklab.github.io/handbook/`](https://bhklab.github.io/handbook/) +to verify that the changes are correct. + +!!!note + To view the latest merged PR changes, ensure you are on the `dev` version of + the site. The version dropdown selector is located next to the site title. ### Delete the branch diff --git a/docs/contributing/release_deployment.md b/docs/contributing/release_deployment.md index 535fa74c..6b797024 100644 --- a/docs/contributing/release_deployment.md +++ b/docs/contributing/release_deployment.md @@ -36,10 +36,10 @@ the latest version of the website. ## Releases and Versioned Documentation -We leverage both [release-please](https://github.com/googleapis/release-please) -and `mike` to automate the release process and manage versioned documentation, -making it easier to maintain version control, changelogs, and multiple -documentation versions. +We leverage both [`release-please`](https://github.com/googleapis/release-please) +and [`mike`](https://github.com/jimporter/mike) to automate the release process +and manage versioned documentation, making it easier to maintain version control, +changelogs, and multiple documentation versions. ### How Releases Work @@ -52,7 +52,7 @@ You can view the release automation action at Key aspects of this combined approach include: -- **Automated Release Creation with release-please**: The tool automatically +- **Automated Release Creation with `release-please`**: The tool automatically generates a release with changelogs and updates the version number based on the changes merged into `main`. - **Dynamic Pull Request Updates**: If additional changes are pushed to the @@ -62,14 +62,13 @@ Key aspects of this combined approach include: - **Controlled Release Process**: Maintainers can merge changes into the release PR only when they are ready to publish a new version, giving them full control over the timing of each release. -- **Versioned Documentation with mike**: Once a new release is prepared, +- **Versioned Documentation with `mike`**: Once a new release is prepared, `mike` is used to manage and deploy versioned documentation. This allows us to provide a separate set of documentation for each release, maintaining historical versions accessible on the website. This automated approach ensures consistency, reduces manual effort, and allows users to access documentation relevant to any specific version of the project. -required to manage releases. ### Manual Release Process diff --git a/docs/contributing/submitting_issues.md b/docs/contributing/submitting_issues.md index 62343746..1cb1164a 100644 --- a/docs/contributing/submitting_issues.md +++ b/docs/contributing/submitting_issues.md @@ -7,7 +7,7 @@ the documentation, you can submit an issue directly on our GitHub repository. We have a set of pre-defined issue templates to help categorize and address your concerns efficiently. -link: [Submit and view issues](https://github.com/bhklab/handbook/issues) +Link: [Submit and view issues](https://github.com/bhklab/handbook/issues) ## Available Issue Templates @@ -44,7 +44,7 @@ When creating a new issue, you will be presented with the following options: 1. Go to the GitHub repository and navigate to the "Issues" tab. 2. Click on the "New Issue" button. -3. Select the appropriate issue template from the list +3. Select the appropriate issue template from the list. 4. Fill out the template, providing as much detail as possible to help us understand and address your issue. 5. Submit the issue. @@ -60,5 +60,3 @@ also select **Open a blank issue** to describe your concern freely. section, page, or example, include links and screenshots to provide context. - **Suggest Solutions**: If you have an idea on how to fix or improve the issue, let us know! Your suggestions can help expedite the process. - -Your feedback is invaluable, and we