Skip to content

Commit 83e57d6

Browse files
ericbsdericbsd
authored
Merge pull request #85 from ghostbsd/maintaining-ports
Adding `Maintaining GhostBSD Ports from FreeBSD Ports`
2 parents cd3ba1f + 04e950f commit 83e57d6

File tree

7 files changed

+164
-7
lines changed

7 files changed

+164
-7
lines changed

‎_static/dark_mode.css‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,3 +195,19 @@ body.dark-mode code.docutils.literal.notranslate {
195195
border-radius: 3px;
196196
border-color: #3c3c3c;
197197
}
198+
199+
/* Dark mode for all admonitions */
200+
body.dark-mode .admonition {
201+
background-color: #2b2b2b; /* Dark background */
202+
/*color: #e0e0e0; /* Light text */
203+
/*border-left: 4px solid #4da8da; /* Light blue accent */
204+
}
205+
206+
body.dark-mode .admonition.note {
207+
/*color: #e0e0e0; /* Light text */
208+
/*border-left: 4px solid #4da8da; /* Light blue accent */
209+
}
210+
211+
body.dark-mode .admonition.note .admonition-title {
212+
background-color: #4da8da; /* Light blue accent */
213+
}

‎conf.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,9 @@
3535

3636
myst_enable_extensions = [
3737
'colon_fence',
38-
'attrs_inline'
38+
'attrs_inline',
39+
'linkify',
40+
'colon_fence'
3941
]
4042

4143
master_doc = 'index'
@@ -66,6 +68,8 @@
6668
'github_version': 'master/',
6769
}
6870

71+
html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }
72+
6973
# Add any paths that contain custom static files (such as style sheets) here,
7074
# relative to this directory. They are copied after the builtin static files,
7175
# so a file named "default.css" will overwrite the builtin "default.css".

‎contributor/ports/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Ports Contribution
2+
3+
Welcome to the GhostBSD ports contribution documentation! Here’s how you can help maintain our ports tree and updated ports.
4+
5+
- [Maintaining GhostBSD Ports in Sync with FreeBSD Ports](maintaining-ports-tree.md) - Learn how to keep our ports current with FreeBSD.

‎contributor/ports/maintaining-ports-tree.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Maintaining GhostBSD Ports from FreeBSD Ports
2+
3+
## Purpose
4+
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.
5+
6+
## Prerequisites
7+
- Git installed and configured with access to GitHub.
8+
- Basic understanding of Git commands and FreeBSD ports structure.
9+
- `poudriere` installed for testing (optional but recommended).
10+
- A local working directory (e.g., `~/ghostbsd-ports`).
11+
12+
---
13+
14+
## Step-by-Step Instructions
15+
16+
### 1. Clone the Repository and Configure Remotes
17+
Clone the GhostBSD ports repository if you don’t already have it:
18+
```shell
19+
git clone https://github.com/ghostbsd/ghostbsd-ports.git
20+
cd ghostbsd-ports
21+
```
22+
Add the FreeBSD ports repository as a remote:
23+
```shell
24+
git remote add freebsd https://github.com/freebsd/freebsd-ports.git
25+
```
26+
Verify the remotes:
27+
```shell
28+
git remote -v
29+
```
30+
Expected output:
31+
```
32+
freebsd https://github.com/freebsd/freebsd-ports.git (fetch)
33+
freebsd https://github.com/freebsd/freebsd-ports.git (push)
34+
origin https://github.com/ghostbsd/ghostbsd-ports.git (fetch)
35+
origin https://github.com/ghostbsd/ghostbsd-ports.git (push)
36+
```
37+
38+
**Note**: If the `freebsd` remote is already set, skip the `git remote add` step.
39+
40+
---
41+
42+
### 2. Create a New Working Branch
43+
Always work in a feature branch to keep `master` clean:
44+
```shell
45+
git checkout master
46+
git pull origin master # Ensure your local master is up-to-date
47+
git checkout -b my-branch-name
48+
```
49+
- Replace `my-branch-name` with a descriptive name (e.g., `sync-freebsd-20250403`).
50+
- This isolates your changes and simplifies pull requests.
51+
52+
---
53+
54+
### 3. Fetch and Merge FreeBSD Ports
55+
Fetch the latest changes from FreeBSD:
56+
```shell
57+
git fetch freebsd
58+
```
59+
Merge FreeBSD’s `master` branch into your branch:
60+
```shell
61+
git merge freebsd/master
62+
```
63+
64+
- **If no conflicts occur**: Proceed to Step 5 (Testing).
65+
- **If conflicts occur**: Continue to Step 4 (Resolving Conflicts).
66+
67+
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:
68+
69+
---
70+
71+
### 4. Resolve Merge Conflicts
72+
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:
73+
```bash
74+
grep -R '<<<<<<< HEAD' .
75+
```
76+
This lists files with conflicts, marked like:
77+
```
78+
<<<<<<< HEAD
79+
# GhostBSD-specific changes (your code)
80+
=======
81+
# FreeBSD changes (upstream code)
82+
>>>>>>> freebsd/master
83+
```
84+
85+
**Resolution Tips**:
86+
- Code conflicts require ports maintenance knowledge but are usually easy—often just changes Git can’t auto-merge.
87+
- **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.
88+
- **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.
89+
- **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).
90+
91+
### 5. Test the Ports Tree (Dry Run)
92+
Before committing, test the updated ports tree with `poudriere`:
93+
```shell
94+
sudo poudriere bulk -j ghostbsd-amd64 -p ghostbsd-ports -an
95+
```
96+
- `-j ghostbsd-amd64`: Specifies the jail (adjust if different).
97+
- `-p ghostbsd-ports`: Uses your local ports tree.
98+
- `-an`: Dry run (analyzes without building).
99+
100+
Check the output for errors. If issues arise, fix the affected ports and repeat.
101+
102+
### 6. Commit and Push Changes
103+
Stage all changes:
104+
```shell
105+
git add -A
106+
```
107+
Commit changes:
108+
```shell
109+
git commit
110+
```
111+
Push to your branch:
112+
```shell
113+
git push origin my-branch-name
114+
```
115+
116+
### 7. Submit Changes
117+
- Create a pull request (PR) on GitHub from `my-branch-name` to `ghostbsd-ports/master`.
118+
- Describe the changes and any resolved conflicts in the PR.
119+
- Await review and approval from maintainers.
120+
121+
:::{note}
122+
Do not push directly to `master` unless you’re a maintainer with explicit permission.
123+
:::
124+
125+
## Common Issues and Solutions
126+
- **Conflict in `Mk` Files**: FreeBSD may update build infrastructure. Retain GhostBSD-specific tweaks (e.g., custom `USES` flags).
127+
- **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.
128+
- **Testing Fails**: Check `poudriere` logs (e.g., `/usr/local/poudriere/data/logs/bulk`) for clues.

‎index-pl.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,18 +23,20 @@ user/FAQ
2323

2424
```{toctree}
2525
:caption: Dokumentacja dla współpracowników
26-
:maxdepth: 4
26+
:maxdepth: 2
2727
:hidden:
2828
29-
contributor/get-involved
30-
contributor/contributor-levels
31-
contributor/ghostbsd-contributors-guide
29+
contributor/index
30+
contributor/getting-started/index
31+
contributor/ports/index
32+
contributor/contributor-levels-pl
33+
contributor/ghostbsd-contributors-guide-pl
3234
```
3335

3436

3537
```{toctree}
3638
:caption: Dokumentacja upstream
37-
:maxdepth: 4
39+
:maxdepth: 2
3840
:hidden:
3941
MATE Documentation <https://wiki.mate-desktop.org/>
4042
FreeBSD Documentation <https://docs.freebsd.org/>

‎index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ user/FAQ
2929
3030
contributor/index
3131
contributor/getting-started/index
32+
contributor/ports/index
3233
contributor/contributor-levels
3334
contributor/ghostbsd-contributors-guide
3435
```

‎requirements.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
myst-parser
2-
sphinx-rtd-theme
2+
sphinx-rtd-theme
3+
linkify-it-py

0 commit comments

Comments
 (0)