Skip to content

Commit 33340f0

Browse files
foo-543674foo-543674
committed
[doc]branch strategy
1 parent 2b52abd commit 33340f0

File tree

1 file changed

+363
-0
lines changed

1 file changed

+363
-0
lines changed

‎BRANCH.md‎

Lines changed: 363 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,363 @@
1+
# Branch Strategy / ブランチ戦略
2+
3+
## English
4+
5+
### Branch Overview
6+
7+
This repository maintains a fork of the upstream flexmark-java project with the following branch structure:
8+
9+
- **`master`**: Internal development branch
10+
- Contains internal deployment configurations and customizations
11+
- Used for internal features and modifications
12+
- **NEVER create PRs from this branch to the upstream repository**
13+
14+
- **`upstream/master`**: Upstream tracking branch
15+
- Maintains exact synchronization with the upstream (fork source) repository
16+
- **Direct pushes are PROHIBITED**
17+
- **Creating/merging PRs within this repository is PROHIBITED**
18+
- **ONLY permitted operation**: Pulling changes from the upstream repository
19+
20+
### Workflow
21+
22+
#### 1. Initial Setup
23+
24+
Set up the upstream remote (one-time setup):
25+
26+
```bash
27+
# Add upstream remote
28+
git remote add upstream [email protected]:vsch/flexmark-java.git
29+
30+
# Verify remotes
31+
git remote -v
32+
# origin [email protected]:nulab/flexmark-java.git (fetch)
33+
# origin [email protected]:nulab/flexmark-java.git (push)
34+
# upstream [email protected]:vsch/flexmark-java.git (fetch)
35+
# upstream [email protected]:vsch/flexmark-java.git (push)
36+
37+
# Fetch upstream branches
38+
git fetch upstream
39+
```
40+
41+
#### 2. For Internal-Only Modifications
42+
43+
For changes that will NOT be contributed back to upstream:
44+
45+
```bash
46+
# Create feature branch from master
47+
git checkout master
48+
git pull origin master
49+
git checkout -b feature/internal-feature
50+
51+
# Make changes and commit
52+
git add .
53+
git commit -m "Add internal feature"
54+
55+
# Push and create PR to master
56+
git push -u origin feature/internal-feature
57+
# Then create PR: feature/internal-feature → master on GitHub
58+
```
59+
60+
#### 3. For Upstream Contributions
61+
62+
For changes that WILL be contributed back to upstream:
63+
64+
**Step 3-1: Create PR directly to upstream repository**
65+
66+
```bash
67+
# Create feature branch from upstream/master
68+
git checkout upstream/master
69+
git pull upstream master
70+
git checkout -b feature/upstream-contribution
71+
72+
# Make changes and commit
73+
git add .
74+
git commit -m "Fix: description of the fix"
75+
76+
# Push to your fork
77+
git push -u origin feature/upstream-contribution
78+
# Create PR: nulab/flexmark-java:feature/upstream-contribution → vsch/flexmark-java:master on GitHub
79+
```
80+
81+
**Step 3-2: After upstream PR is merged**
82+
83+
```bash
84+
# Update upstream/master from upstream repository
85+
git checkout upstream/master
86+
git pull upstream master
87+
88+
# Verify the merge
89+
git log --oneline -5
90+
91+
# Push updated upstream/master to origin
92+
git push origin upstream/master
93+
```
94+
95+
**Step 3-3: Sync changes to master**
96+
97+
```bash
98+
# Create sync branch from updated upstream/master
99+
git checkout upstream/master
100+
git checkout -b sync/upstream-to-master
101+
102+
# Push and create PR to master
103+
git push -u origin sync/upstream-to-master
104+
# Then create PR: sync/upstream-to-master → master on GitHub
105+
```
106+
107+
#### 4. Regular Upstream Synchronization
108+
109+
Keep `upstream/master` up-to-date with upstream repository:
110+
111+
```bash
112+
# Update upstream/master
113+
git checkout upstream/master
114+
git pull upstream master
115+
git push origin upstream/master
116+
117+
# If there are updates, sync to master
118+
git checkout -b sync/upstream-$(date +%Y%m%d)
119+
git push -u origin sync/upstream-$(date +%Y%m%d)
120+
# Create PR: sync/upstream-YYYYMMDD → master on GitHub
121+
```
122+
123+
### Important Rules
124+
125+
1. ✅ **Permitted Operations**
126+
- Create PRs from feature branches to `master`
127+
- Create PRs directly to upstream repository
128+
- Create PRs from `upstream/master` to `master`
129+
- Pull changes from upstream to `upstream/master`
130+
131+
2. ❌ **PROHIBITED Operations**
132+
- Creating PRs from `master` to upstream repository
133+
- Direct pushes to `upstream/master`
134+
- Creating/merging PRs targeting `upstream/master` within this repository
135+
- Any modifications to `upstream/master` except pulling from upstream
136+
137+
### Branch Protection Recommendations
138+
139+
Configure the following branch protection rules on GitHub:
140+
141+
**For `upstream/master` branch:**
142+
- Require pull request reviews before merging: **OFF** (PRs should not be created)
143+
- Require status checks to pass: **OFF**
144+
- Restrict who can push: **Enable** (no one should push directly)
145+
- Lock branch: **Consider enabling** (to prevent accidental modifications)
146+
147+
**For `master` branch:**
148+
- Require pull request reviews before merging: **ON**
149+
- Require status checks to pass: **ON** (if CI is configured)
150+
- Dismiss stale pull request approvals: **ON**
151+
152+
---
153+
154+
## 日本語
155+
156+
### ブランチ概要
157+
158+
このリポジトリはupstream（flexmark-java）のフォークであり、以下のブランチ構成で運用します：
159+
160+
- **`master`**: 社内開発用ブランチ
161+
- 社内のデプロイ設定やカスタマイズを含む
162+
- 社内専用の機能追加や修正に使用
163+
- **このブランチからupstreamへのPRは絶対に作成しない**
164+
165+
- **`upstream/master`**: upstream追従ブランチ
166+
- Fork元（upstream）と完全に同期を保つ
167+
- **直接プッシュ禁止**
168+
- **このリポジトリ内でのPR作成・マージ禁止**
169+
- **許可される操作**: upstreamからのpullのみ
170+
171+
### ワークフロー
172+
173+
#### 1. 初期セットアップ
174+
175+
upstreamリモートの設定（初回のみ）：
176+
177+
```bash
178+
# upstreamリモートを追加
179+
git remote add upstream [email protected]:vsch/flexmark-java.git
180+
181+
# リモートの確認
182+
git remote -v
183+
# origin [email protected]:nulab/flexmark-java.git (fetch)
184+
# origin [email protected]:nulab/flexmark-java.git (push)
185+
# upstream [email protected]:vsch/flexmark-java.git (fetch)
186+
# upstream [email protected]:vsch/flexmark-java.git (push)
187+
188+
# upstreamのブランチをフェッチ
189+
git fetch upstream
190+
```
191+
192+
#### 2. 社内専用の修正を行う場合
193+
194+
upstreamに出さない修正の場合：
195+
196+
```bash
197+
# masterから機能ブランチを作成
198+
git checkout master
199+
git pull origin master
200+
git checkout -b feature/internal-feature
201+
202+
# 変更をコミット
203+
git add .
204+
git commit -m "社内機能の追加"
205+
206+
# プッシュしてmasterへPR作成
207+
git push -u origin feature/internal-feature
208+
# GitHub上で PR作成: feature/internal-feature → master
209+
```
210+
211+
#### 3. upstreamに貢献する修正を行う場合
212+
213+
upstreamに出す修正の場合：
214+
215+
**手順3-1: upstream（Fork元）に直接PRを作成**
216+
217+
```bash
218+
# upstream/masterから機能ブランチを作成
219+
git checkout upstream/master
220+
git pull upstream master
221+
git checkout -b feature/upstream-contribution
222+
223+
# 変更をコミット
224+
git add .
225+
git commit -m "Fix: 修正内容の説明"
226+
227+
# 自分のforkにプッシュ
228+
git push -u origin feature/upstream-contribution
229+
# GitHub上で PR作成: nulab/flexmark-java:feature/upstream-contribution → vsch/flexmark-java:master
230+
```
231+
232+
**手順3-2: upstreamでPRがマージされた後**
233+
234+
```bash
235+
# upstream/masterをupstreamリポジトリから更新
236+
git checkout upstream/master
237+
git pull upstream master
238+
239+
# マージされたことを確認
240+
git log --oneline -5
241+
242+
# 更新したupstream/masterをoriginにプッシュ
243+
git push origin upstream/master
244+
```
245+
246+
**手順3-3: 変更をmasterに同期**
247+
248+
```bash
249+
# 更新されたupstream/masterから同期ブランチを作成
250+
git checkout upstream/master
251+
git checkout -b sync/upstream-to-master
252+
253+
# プッシュしてmasterへPR作成
254+
git push -u origin sync/upstream-to-master
255+
# GitHub上で PR作成: sync/upstream-to-master → master
256+
```
257+
258+
#### 4. 定期的なupstream同期
259+
260+
`upstream/master`をupstreamリポジトリと同期：
261+
262+
```bash
263+
# upstream/masterを更新
264+
git checkout upstream/master
265+
git pull upstream master
266+
git push origin upstream/master
267+
268+
# 更新がある場合、masterに同期
269+
git checkout -b sync/upstream-$(date +%Y%m%d)
270+
git push -u origin sync/upstream-$(date +%Y%m%d)
271+
# GitHub上で PR作成: sync/upstream-YYYYMMDD → master
272+
```
273+
274+
### 重要なルール
275+
276+
1. ✅ **許可される操作**
277+
- 機能ブランチから`master`へのPR作成
278+
- upstreamリポジトリへの直接PR作成
279+
- `upstream/master`から`master`へのPR作成
280+
- upstreamから`upstream/master`への変更のpull
281+
282+
2. ❌ **禁止される操作**
283+
- `master`からupstreamリポジトリへのPR作成
284+
- `upstream/master`への直接プッシュ
285+
- このリポジトリ内での`upstream/master`を対象とするPR作成・マージ
286+
- upstreamからのpull以外での`upstream/master`の変更
287+
288+
### ブランチ保護設定の推奨
289+
290+
GitHub上で以下のブランチ保護ルールを設定することを推奨します：
291+
292+
**`upstream/master`ブランチ:**
293+
- マージ前にプルリクエストレビューを必須: **OFF**（PRは作成されないため）
294+
- ステータスチェックの合格を必須: **OFF**
295+
- プッシュ可能なユーザーを制限: **ON**（誰も直接プッシュできないように）
296+
- ブランチをロック: **検討する**（誤った変更を防ぐため）
297+
298+
**`master`ブランチ:**
299+
- マージ前にプルリクエストレビューを必須: **ON**
300+
- ステータスチェックの合格を必須: **ON**（CIが設定されている場合）
301+
- 古いプルリクエストの承認を却下: **ON**
302+
303+
---
304+
305+
## Diagram / 図解
306+
307+
```
308+
Upstream Repository (vsch/flexmark-java)
309+
↓ pull only
310+
upstream/master ────PR───→ master (Internal Development)
311+
↑ ↑
312+
│ │
313+
└─ feature branches ──────┘
314+
(for upstream) (for internal)
315+
```
316+
317+
### Flow Summary / フロー概要
318+
319+
```
320+
Internal Only:
321+
master → feature/xxx → PR → master
322+
323+
Upstream Contribution:
324+
1. upstream/master → feature/xxx → PR → vsch/flexmark-java:master
325+
2. (after merge) vsch/flexmark-java:master → pull → upstream/master
326+
3. upstream/master → sync/xxx → PR → master
327+
```
328+
329+
---
330+
331+
## Troubleshooting / トラブルシューティング
332+
333+
### Accidentally committed to upstream/master / 誤ってupstream/masterにコミットしてしまった場合
334+
335+
```bash
336+
# Reset to match upstream (WARNING: discards local commits)
337+
git checkout upstream/master
338+
git fetch upstream
339+
git reset --hard upstream/master
340+
git push -f origin upstream/master
341+
```
342+
343+
### Conflict when syncing upstream to master / upstreamからmasterへの同期で競合が発生した場合
344+
345+
```bash
346+
# On sync branch
347+
git checkout sync/upstream-to-master
348+
git merge master
349+
# Resolve conflicts
350+
git add .
351+
git commit -m "Merge master and resolve conflicts"
352+
git push origin sync/upstream-to-master
353+
```
354+
355+
### Lost track of upstream/master / upstream/masterの追跡を見失った場合
356+
357+
```bash
358+
# Re-create upstream/master branch
359+
git fetch upstream
360+
git branch -D upstream/master
361+
git checkout -b upstream/master upstream/master
362+
git push -f origin upstream/master
363+
```

0 commit comments

Comments
 (0)