Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update zh-TW translation #401

Open
wants to merge 1 commit into
base: gh-pages
Choose a base branch
from
Open

Update zh-TW translation #401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions lang/zh-TW/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ language: zh-TW

在軟體管理的領域裡存在著被稱作「相依性地獄」的死亡之谷，系統規模越大，加入的套件越多，你就越有可能在未來的某一天發現自己已深陷絕望之中。

在相依性高的系統中發佈新版本套件可能很快會成為惡夢。如果相依性關係過高，可能面臨版本控制被鎖死的風險（必須對每一個相依套件改版才能完成某次升級）。而如果相依性關係過於鬆散，又將無法避免版本的混亂（假設相容於未來的多個版本已超出了合理數量）。當你專案的進展因為版本相依被鎖死或版本混亂變得不夠簡便和可靠，就意味著你正處於相依性地獄之中。
在相依性高的系統中發行新版本套件可能很快會成為惡夢。如果相依性關係過高，可能面臨版本控制被鎖死的風險（必須對每一個相依套件改版才能完成某次升級）。而如果相依性關係過於鬆散，又將無法避免版本的混亂（假設相容於未來的多個版本已超出了合理數量）。當你專案的進展因為版本相依被鎖死或版本混亂變得不夠簡便和可靠，就意味著你正處於相依性地獄之中。

作為這個問題的解決方案之一，我提議用一組簡單的規則及條件來約束版號的配置和增長。這些規則是根據（但不局限於）已經被各種封閉、開放源碼軟體所廣泛使用的慣例所設計。為了讓這套理論運作，你必須先有定義好的公共 API。這可以透過文件定義或程式碼強制要求來實現。無論如何，這套 API 的清楚明瞭是十分重要的。一旦你定義了公共 API，你就可以透過修改相應的版號來向大家說明你的修改。考慮使用這樣的版號格式：X.Y.Z（主版號.次版號.修訂號）修復問題但不影響 API 時，遞增修訂號；API 保持向下相容的新增及修改時，遞增次版號；進行不向下相容的修改時，遞增主版號。

Expand Down Expand Up @@ -148,7 +148,7 @@ language: zh-TW

這並不是一個新的或者革命性的想法。實際上，你可能已經在做一些近似的事情了。問題在於只是「近似」還不夠。如果沒有某個正式的規範可循，版號對於相依性的管理並無實質意義。將上述的想法命名並給予清楚的定義，讓你對軟體使用者傳達意向變得容易。一旦這些意向變得清楚，彈性（但又不會太彈性）的相依性規範就能達成。

舉個簡單的例子就可以展示語意化的版本控制如何讓相依性地獄成為過去。假設有個名為「消防車」的函式庫，它需要另一個名為「梯子」並已經有使用語意化版本控制的套件。當消防車創建時，梯子的版號為 3.1.0。因為消防車使用了一些版本 3.1.0 所新增的功能，你可以放心地指定相依於梯子的版號大等於 3.1.0 但小於4.0.0。這樣，當梯子版本 3.1.1和 3.2.0 發佈時，你可以將直接它們納入你的套件管理系統，因為它們能與原有相依的軟體相容。
舉個簡單的例子就可以展示語意化的版本控制如何讓相依性地獄成為過去。假設有個名為「消防車」的函式庫，它需要另一個名為「梯子」並已經有使用語意化版本控制的套件。當消防車創建時，梯子的版號為 3.1.0。因為消防車使用了一些版本 3.1.0 所新增的功能，你可以放心地指定相依於梯子的版號大等於 3.1.0 但小於4.0.0。這樣，當梯子版本 3.1.1和 3.2.0 發行時，你可以將直接它們納入你的套件管理系統，因為它們能與原有相依的軟體相容。

作為一位負責任的開發者，你理當確保每次套件升級的運作與版本號的表述一致。現實世界是複雜的，我們除了提高警覺外能做的不多。你所能做的就是讓語意化的版本控制為你提供一個健全的方式來發行以及升級套件，而無需推出新的相依套件，節省你的時間及煩惱。

Expand All @@ -161,7 +161,7 @@ FAQ

最簡單的做法是以 0.1.0 作為你的初始化開發版本，並在後續的每次發行時遞增次版號。

### 如何判斷發佈 1.0.0 版本的時機？
### 如何判斷發行 1.0.0 版本的時機？

當你的軟體被用於正式環境，它應該已經達到了 1.0.0 版。如果你已經有個穩定的 API 被使用者依賴，也會是 1.0.0 版。如果你很擔心向下相容的問題，也應該算是 1.0.0 版了。

Expand All @@ -185,13 +185,13 @@ FAQ

由於沒有影響到公共 API，這可以被認定是相容的。若某個軟體和你的套件有共同相依性，則它會有自己的相依性規範，作者也會告知可能的衝突。要判斷改版是屬於修訂等級或是次版等級，是依據你更新的相依性關係是為了修復問題或是加入新功能。對於後者，我經常會預期伴隨著更多的程式碼，這顯然會是一個次版號級別的遞增。

### 如果我變更了公共 API 但無意中未遵循版號的改動怎麼辦呢？（意即在修訂等級的發佈中，誤將重大且不相容的改變加到程式碼之中）
### 如果我變更了公共 API 但無意中未遵循版號的改動怎麼辦呢？（意即在修訂等級的發行中，誤將重大且不相容的改變加到程式碼之中）

自行做最佳的判斷。如果你有龐大的使用者群在依照公共 API 的意圖而變更行為後會大受影響，那麼最好做一次主版本的發佈，即使嚴格來說這個修復僅是修訂等級的發佈。記住，語意化的版本控制就是透過版號的改變來傳達意義。若這些改變對你的使用者是重要的，那就透過版號來向他們說明。
自行做最佳的判斷。如果你有龐大的使用者群在依照公共 API 的意圖而變更行為後會大受影響，那麼最好做一次主版本的發行，即使嚴格來說這個修復僅是修訂等級的發行。記住，語意化的版本控制就是透過版號的改變來傳達意義。若這些改變對你的使用者是重要的，那就透過版號來向他們說明。

### 我該如何處理即將棄用的功能？

棄用現存的功能是軟體開發中的家常便飯，也通常是向前發展所必須的。當你棄用部份公共 API 時，你應該做兩件事：（1）更新你的文件讓使用者知道這個改變，（2）在適當的時機將棄用的功能透過新的次版號發佈。在新的主版本完全移除棄用功能前，至少要有一個次版本包含這個棄用資訊，這樣使用者才能平順地轉移到新版 API。
棄用現存的功能是軟體開發中的家常便飯，也通常是向前發展所必須的。當你棄用部份公共 API 時，你應該做兩件事：（1）更新你的文件讓使用者知道這個改變，（2）在適當的時機將棄用的功能透過新的次版號發行。在新的主版本完全移除棄用功能前，至少要有一個次版本包含這個棄用資訊，這樣使用者才能平順地轉移到新版 API。

### 語意化版本對於版本的字串長度是否有限制呢？

Expand Down
12 changes: 6 additions & 6 deletions lang/zh-TW/spec/v2.0.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ language: zh-TW

在軟體管理的領域裡存在著被稱作「相依性地獄」的死亡之谷，系統規模越大，加入的套件越多，你就越有可能在未來的某一天發現自己已深陷絕望之中。

在相依性高的系統中發佈新版本套件可能很快會成為惡夢。如果相依性關係過高，可能面臨版本控制被鎖死的風險（必須對每一個相依套件改版才能完成某次升級）。而如果相依性關係過於鬆散，又將無法避免版本的混亂（假設相容於未來的多個版本已超出了合理數量）。當你專案的進展因為版本相依被鎖死或版本混亂變得不夠簡便和可靠，就意味著你正處於相依性地獄之中。
在相依性高的系統中發行新版本套件可能很快會成為惡夢。如果相依性關係過高，可能面臨版本控制被鎖死的風險（必須對每一個相依套件改版才能完成某次升級）。而如果相依性關係過於鬆散，又將無法避免版本的混亂（假設相容於未來的多個版本已超出了合理數量）。當你專案的進展因為版本相依被鎖死或版本混亂變得不夠簡便和可靠，就意味著你正處於相依性地獄之中。

作為這個問題的解決方案之一，我提議用一組簡單的規則及條件來約束版號的配置和增長。這些規則是根據（但不局限於）已經被各種封閉、開放源碼軟體所廣泛使用的慣例所設計。為了讓這套理論運作，你必須先有定義好的公共 API。這可以透過文件定義或程式碼強制要求來實現。無論如何，這套 API 的清楚明瞭是十分重要的。一旦你定義了公共 API，你就可以透過修改相應的版號來向大家說明你的修改。考慮使用這樣的版號格式：X.Y.Z（主版號.次版號.修訂號）修復問題但不影響 API 時，遞增修訂號；API 保持向下相容的新增及修改時，遞增次版號；進行不向下相容的修改時，遞增主版號。

Expand Down Expand Up @@ -60,7 +60,7 @@ language: zh-TW

這並不是一個新的或者革命性的想法。實際上，你可能已經在做一些近似的事情了。問題在於只是「近似」還不夠。如果沒有某個正式的規範可循，版號對於相依性的管理並無實質意義。將上述的想法命名並給予清楚的定義，讓你對軟體使用者傳達意向變得容易。一旦這些意向變得清楚，彈性（但又不會太彈性）的相依性規範就能達成。

舉個簡單的例子就可以展示語意化的版本控制如何讓相依性地獄成為過去。假設有個名為「消防車」的函式庫，它需要另一個名為「梯子」並已經有使用語意化版本控制的套件。當消防車創建時，梯子的版號為 3.1.0。因為消防車使用了一些版本 3.1.0 所新增的功能，你可以放心地指定相依於梯子的版號大等於 3.1.0 但小於4.0.0。這樣，當梯子版本 3.1.1和 3.2.0 發佈時，你可以將直接它們納入你的套件管理系統，因為它們能與原有相依的軟體相容。
舉個簡單的例子就可以展示語意化的版本控制如何讓相依性地獄成為過去。假設有個名為「消防車」的函式庫，它需要另一個名為「梯子」並已經有使用語意化版本控制的套件。當消防車創建時，梯子的版號為 3.1.0。因為消防車使用了一些版本 3.1.0 所新增的功能，你可以放心地指定相依於梯子的版號大等於 3.1.0 但小於4.0.0。這樣，當梯子版本 3.1.1和 3.2.0 發行時，你可以將直接它們納入你的套件管理系統，因為它們能與原有相依的軟體相容。

作為一位負責任的開發者，你理當確保每次套件升級的運作與版本號的表述一致。現實世界是複雜的，我們除了提高警覺外能做的不多。你所能做的就是讓語意化的版本控制為你提供一個健全的方式來發行以及升級套件，而無需推出新的相依套件，節省你的時間及煩惱。

Expand All @@ -73,7 +73,7 @@ FAQ

最簡單的做法是以 0.1.0 作為你的初始化開發版本，並在後續的每次發行時遞增次版號。

### 如何判斷發佈 1.0.0 版本的時機？
### 如何判斷發行 1.0.0 版本的時機？

當你的軟體被用於正式環境，它應該已經達到了 1.0.0 版。如果你已經有個穩定的 API 被使用者依賴，也會是 1.0.0 版。如果你很擔心向下相容的問題，也應該算是 1.0.0 版了。

Expand All @@ -97,13 +97,13 @@ FAQ

由於沒有影響到公共 API，這可以被認定是相容的。若某個軟體和你的套件有共同相依性，則它會有自己的相依性規範，作者也會告知可能的衝突。要判斷改版是屬於修訂等級或是次版等級，是依據你更新的相依性關係是為了修復問題或是加入新功能。對於後者，我經常會預期伴隨著更多的程式碼，這顯然會是一個次版號級別的遞增。

### 如果我變更了公共 API 但無意中未遵循版號的改動怎麼辦呢？（意即在修訂等級的發佈中，誤將重大且不相容的改變加到程式碼之中）
### 如果我變更了公共 API 但無意中未遵循版號的改動怎麼辦呢？（意即在修訂等級的發行中，誤將重大且不相容的改變加到程式碼之中）

自行做最佳的判斷。如果你有龐大的使用者群在依照公共 API 的意圖而變更行為後會大受影響，那麼最好做一次主版本的發佈，即使嚴格來說這個修復僅是修訂等級的發佈。記住，語意化的版本控制就是透過版號的改變來傳達意義。若這些改變對你的使用者是重要的，那就透過版號來向他們說明。
自行做最佳的判斷。如果你有龐大的使用者群在依照公共 API 的意圖而變更行為後會大受影響，那麼最好做一次主版本的發行，即使嚴格來說這個修復僅是修訂等級的發行。記住，語意化的版本控制就是透過版號的改變來傳達意義。若這些改變對你的使用者是重要的，那就透過版號來向他們說明。

### 我該如何處理即將棄用的功能？

棄用現存的功能是軟體開發中的家常便飯，也通常是向前發展所必須的。當你棄用部份公共 API 時，你應該做兩件事：（1）更新你的文件讓使用者知道這個改變，（2）在適當的時機將棄用的功能透過新的次版號發佈。在新的主版本完全移除棄用功能前，至少要有一個次版本包含這個棄用資訊，這樣使用者才能平順地轉移到新版 API。
棄用現存的功能是軟體開發中的家常便飯，也通常是向前發展所必須的。當你棄用部份公共 API 時，你應該做兩件事：（1）更新你的文件讓使用者知道這個改變，（2）在適當的時機將棄用的功能透過新的次版號發行。在新的主版本完全移除棄用功能前，至少要有一個次版本包含這個棄用資訊，這樣使用者才能平順地轉移到新版 API。

### 語意化版本對於版本的字串長度是否有限制呢？

Expand Down