Skip to content

Commit 2e1a062

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

File tree

2 files changed

+386
-0
lines changed

2 files changed

+386
-0
lines changed

‎BRANCH.md‎

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

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
![Flexmark Icon Logo](assets/images/flexmark-icon-logo.png) flexmark-java
22
=========================================================================
33

4+
:warning: **Branch Strategy**: This is a fork of the upstream flexmark-java project. Please read [BRANCH.md](BRANCH.md) for our branch management strategy and contribution workflow.
5+
6+
---
7+
48
**flexmark-java** is a Java implementation of **[CommonMark (spec 0.28)]** parser using the
59
blocks first, inlines after Markdown parsing architecture.
610

0 commit comments

Comments
 (0)