diff --git a/_static/dark_mode.css b/_static/dark_mode.css index 7c35c08..db07c71 100644 --- a/_static/dark_mode.css +++ b/_static/dark_mode.css @@ -195,3 +195,19 @@ body.dark-mode code.docutils.literal.notranslate { border-radius: 3px; border-color: #3c3c3c; } + +/* Dark mode for all admonitions */ +body.dark-mode .admonition { + background-color: #2b2b2b; /* Dark background */ + /*color: #e0e0e0; /* Light text */ + /*border-left: 4px solid #4da8da; /* Light blue accent */ +} + +body.dark-mode .admonition.note { + /*color: #e0e0e0; /* Light text */ + /*border-left: 4px solid #4da8da; /* Light blue accent */ +} + +body.dark-mode .admonition.note .admonition-title { + background-color: #4da8da; /* Light blue accent */ +} \ No newline at end of file diff --git a/conf.py b/conf.py index ffc2516..f7683e1 100644 --- a/conf.py +++ b/conf.py @@ -35,7 +35,9 @@ myst_enable_extensions = [ 'colon_fence', - 'attrs_inline' + 'attrs_inline', + 'linkify', + 'colon_fence' ] master_doc = 'index' @@ -66,6 +68,8 @@ 'github_version': 'master/', } +html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] } + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/contributor/ports/index.md b/contributor/ports/index.md new file mode 100644 index 0000000..08ed25c --- /dev/null +++ b/contributor/ports/index.md @@ -0,0 +1,5 @@ +# Ports Contribution + +Welcome to the GhostBSD ports contribution documentation! Here’s how you can help maintain our ports tree and updated ports. + +- [Maintaining GhostBSD Ports in Sync with FreeBSD Ports](maintaining-ports-tree.md) - Learn how to keep our ports current with FreeBSD. \ No newline at end of file diff --git a/contributor/ports/maintaining-ports-tree.md b/contributor/ports/maintaining-ports-tree.md new file mode 100644 index 0000000..7db6875 --- /dev/null +++ b/contributor/ports/maintaining-ports-tree.md @@ -0,0 +1,128 @@ +# Maintaining GhostBSD Ports from FreeBSD Ports + +## Purpose +This guide explains how to keep the GhostBSD ports tree (https://github.com/ghostbsd/ghostbsd-ports) current with the upstream FreeBSD ports tree (https://github.com/freebsd/freebsd-ports), resolve merge conflicts, and test changes before submission. + +## Prerequisites +- Git installed and configured with access to GitHub. +- Basic understanding of Git commands and FreeBSD ports structure. +- `poudriere` installed for testing (optional but recommended). +- A local working directory (e.g., `~/ghostbsd-ports`). + +--- + +## Step-by-Step Instructions + +### 1. Clone the Repository and Configure Remotes +Clone the GhostBSD ports repository if you don’t already have it: +```shell +git clone https://github.com/ghostbsd/ghostbsd-ports.git +cd ghostbsd-ports +``` +Add the FreeBSD ports repository as a remote: +```shell +git remote add freebsd https://github.com/freebsd/freebsd-ports.git +``` +Verify the remotes: +```shell +git remote -v +``` +Expected output: +``` +freebsd https://github.com/freebsd/freebsd-ports.git (fetch) +freebsd https://github.com/freebsd/freebsd-ports.git (push) +origin https://github.com/ghostbsd/ghostbsd-ports.git (fetch) +origin https://github.com/ghostbsd/ghostbsd-ports.git (push) +``` + +**Note**: If the `freebsd` remote is already set, skip the `git remote add` step. + +--- + +### 2. Create a New Working Branch +Always work in a feature branch to keep `master` clean: +```shell +git checkout master +git pull origin master # Ensure your local master is up-to-date +git checkout -b my-branch-name +``` +- Replace `my-branch-name` with a descriptive name (e.g., `sync-freebsd-20250403`). +- This isolates your changes and simplifies pull requests. + +--- + +### 3. Fetch and Merge FreeBSD Ports +Fetch the latest changes from FreeBSD: +```shell +git fetch freebsd +``` +Merge FreeBSD’s `master` branch into your branch: +```shell +git merge freebsd/master +``` + +- **If no conflicts occur**: Proceed to Step 5 (Testing). +- **If conflicts occur**: Continue to Step 4 (Resolving Conflicts). + +You’re right—my wording for directory conflicts suggests restoring GhostBSD’s version when FreeBSD renames or removes a directory, but you want the resolver to ensure files are moved and the old directory is removed, aligning with FreeBSD’s change. Here’s the corrected section: + +--- + +### 4. Resolve Merge Conflicts +Conflicts typically come from GhostBSD-specific changes (e.g., `Mk` files, `Makefiles`). FreeBSD updates, like renamed or removed directories, can also affect merges. Check https://github.com/freebsd/freebsd-ports for upstream changes. To find code conflicts: +```bash +grep -R '<<<<<<< HEAD' . +``` +This lists files with conflicts, marked like: +``` +<<<<<<< HEAD +# GhostBSD-specific changes (your code) +======= +# FreeBSD changes (upstream code) +>>>>>>> freebsd/master +``` + +**Resolution Tips**: +- Code conflicts require ports maintenance knowledge but are usually easy—often just changes Git can’t auto-merge. +- **Keep GhostBSD changes**: Always preserve our customizations (e.g., in `Mk` files or `Makefiles`, the most common conflict sources), especially fixes made before FreeBSD or changes to default options. +- **Resolve `PORTVERSION` conflicts**: For `Makefile` `PORTVERSION`, use FreeBSD’s version (e.g., `1.2.4`) unless a comment above ours (e.g., `# Keep 1.2.3 for GhostBSD fix`) says to keep it. +- **Handle directory conflicts**: If FreeBSD renamed or removed a directory, ensure all files are moved to the new location and remove the old directory (use `git status` to spot added/removed files). + +### 5. Test the Ports Tree (Dry Run) +Before committing, test the updated ports tree with `poudriere`: +```shell +sudo poudriere bulk -j ghostbsd-amd64 -p ghostbsd-ports -an +``` +- `-j ghostbsd-amd64`: Specifies the jail (adjust if different). +- `-p ghostbsd-ports`: Uses your local ports tree. +- `-an`: Dry run (analyzes without building). + +Check the output for errors. If issues arise, fix the affected ports and repeat. + +### 6. Commit and Push Changes +Stage all changes: +```shell +git add -A +``` +Commit changes: +```shell +git commit +``` +Push to your branch: +```shell +git push origin my-branch-name +``` + +### 7. Submit Changes +- Create a pull request (PR) on GitHub from `my-branch-name` to `ghostbsd-ports/master`. +- Describe the changes and any resolved conflicts in the PR. +- Await review and approval from maintainers. + +:::{note} +Do not push directly to `master` unless you’re a maintainer with explicit permission. +::: + +## Common Issues and Solutions +- **Conflict in `Mk` Files**: FreeBSD may update build infrastructure. Retain GhostBSD-specific tweaks (e.g., custom `USES` flags). +- **Renamed/Removed Directories**: If FreeBSD renamed or removed a directory, ensure all files are moved to the new location and delete the old directory during conflict resolution. +- **Testing Fails**: Check `poudriere` logs (e.g., `/usr/local/poudriere/data/logs/bulk`) for clues. diff --git a/index-pl.md b/index-pl.md index c642852..f708550 100644 --- a/index-pl.md +++ b/index-pl.md @@ -23,18 +23,20 @@ user/FAQ ```{toctree} :caption: Dokumentacja dla współpracowników -:maxdepth: 4 +:maxdepth: 2 :hidden: -contributor/get-involved -contributor/contributor-levels -contributor/ghostbsd-contributors-guide +contributor/index +contributor/getting-started/index +contributor/ports/index +contributor/contributor-levels-pl +contributor/ghostbsd-contributors-guide-pl ``` ```{toctree} :caption: Dokumentacja upstream -:maxdepth: 4 +:maxdepth: 2 :hidden: MATE Documentation FreeBSD Documentation diff --git a/index.md b/index.md index 8445403..2cdfff3 100644 --- a/index.md +++ b/index.md @@ -29,6 +29,7 @@ user/FAQ contributor/index contributor/getting-started/index +contributor/ports/index contributor/contributor-levels contributor/ghostbsd-contributors-guide ``` diff --git a/requirements.txt b/requirements.txt index 6692370..0fda02f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,3 @@ myst-parser -sphinx-rtd-theme \ No newline at end of file +sphinx-rtd-theme +linkify-it-py \ No newline at end of file