我在 WordPress。org 上放置的第一個插件九天都沒有發貨。我已經提交了程式碼,標記了版本,用我的新描述觀看了列表更新,並告訴人們它已經發布了。下載量保持平穩,因為下載按鈕提供的是一個空標籤資料夾:我的 readme.txt 說 Stable tag: 1.0.1 我實際創建的標籤是 1.0. 沒有任何警告我。目錄完全按照我的指示做了。
該行是 WordPress 外掛程式中風險最高的欄位's readme.txt,它是安靜而不是大聲失敗的幾個之一。本指南按照損壞發生的順序介紹了目錄對該文件每個部分的作用。這 WordPress 自述文件產生器 使用附加到它們所應用的欄位中的這些規則來建立檔案。
TL;DR:
Stable tag命名目錄實際服務的版本。它是從中讀取的trunk/readme.txt,它指向下面的資料夾/tags/它必須存在並且必須包含版本。如果它命名了不存在的版本,則用戶什麼也得不到;如果它仍然命名舊代碼,無論您承諾什麼,他們都會獲得舊代碼。Tested up to控制清單上的相容性警告,Tags僅索引前五個,簡短的描述被削減為 150 個字元。
Stable 標籤實際上控制什麼?
目錄中的一個插件位於 Subversion 中,具有 trunk/ 對於目前的發展和 tags/<version>/ 對於發布。當有人點擊下載時,目錄不會發送它們 trunk. 它讀到 trunk/readme.txt,發現 Stable tag,並服務 tags/<that value>/.
接下來是三個後果,這三個後果都咬住了真正的釋放:
- 決定這一點的自述文件是中繼中的自述文件。 在標籤資料夾中編輯自述文件不會改變任何內容。
- 標籤必須存在。 一個
Stable tag命名從未建立的資料夾意味著下載為空或失敗。 - 中繼不是用戶收到的。 您可以承諾整週使用中繼;在穩定標籤移動之前,發布的程式碼就是舊標籤所包含的任何程式碼。
的 插件手冊 清楚地說明了該規則,值得正確閱讀一次,而不是從另一個插件複製自述文件並編輯欄位。一個值得知道的例外: Stable tag: trunk 確實意味著&引用;服務中繼&引用;這是合法的,也是少數插件的發布方式。這也意味著對中繼的每個提交都會立即為每個用戶生效,這就是為什麼幾乎沒有人應該這樣做。
發布的後半部分,自述文件根本無法控制。版本在 Stable tag 必須匹配 Version: 主插件 PHP 檔案中的標頭,因為這是已安裝網站在決定是否存在更新時所比較的標頭。運送一個標籤,其插件標頭仍然顯示先前的數字,並且目錄提供更新,安裝聲稱是已存在版本的內容。
每個標題行對您的清單有何作用
標頭塊是九行普通 Key: value 他們每個人都改變了一些可見的東西。
| 線 | 它做什麼 | 出了什麼問題 |
|---|---|---|
Stable tag |
選擇所提供的版本 | 錯誤的值不會發送任何內容,或發送舊代碼 |
Requires at least |
最小 WordPress 版本 | 安裝的區塊太高,這可以工作 |
Tested up to |
相容性聲明 | 落在後面顯示一個"未測試"警告 |
Requires PHP |
最小 PHP 版本 | 太低會導致不相容的網站安裝和失敗 |
Tags |
目錄關鍵字 | 只有前五個被索引 |
Contributors |
連結 WordPress.org 設定檔 | 打字錯誤默默地沒有註明出處 |
Donate link |
側邊欄捐贈按鈕 | 缺席就好,不破 |
License / License URI |
許可證 | 必須相容於 GPL 才能列出 |
Tested up to 是默默下載成本較高的一個。當它落後了幾個核心版本時,該列表會顯示一條通知,告訴訪客該插件未經其版本的 WordPress 測試,並且看起來被遺棄的插件無論是否有效都會安裝更少。更新該行是對中繼的自述承諾,需要一分鐘,這是生態系統中最便宜的維護。
Tags 索引五。第六個標籤不是錯誤,也不會產生任何警告;它只是檔案中的死文字。選擇實際輸入的五個人。
描述是如何分裂的?為什麼它很重要?
自述文件中有兩種描述,它們執行不同的工作。
的 簡短的描述 是標題行和第一行之間的單一文字區塊 == Section ==. 它的上限為 150 個字符,超過該目錄會在搜尋結果和插件卡上截斷它,通常是句子中間。這是大多數人在決定是否單擊之前閱讀的行,這使得 150 個字符成為文件中最有價值的房地產。
的 長描述 是 == Description == 部分,它成為您的清單頁面的正文。它需要 Markdown 的子集:標題、粗體、斜體、清單、連結。原始 HTML 被剝離。表格、帶有語法突出顯示的圍欄程式碼區塊以及更奇特的 Markdown 不會渲染,因此在 Markdown 預覽器中看起來正確的自述文件在 WordPress。org 上仍然可能看起來錯誤。
其他部分均對應到清單上的選項卡:
== Description == the main body
== Installation == the Installation tab
== Frequently Asked Questions == the FAQ tab, one "= question =" per entry
== Screenshots == numbered captions, matched to files in /assets/
== Changelog == one "= version =" block per release, newest first
== Upgrade Notice == the short line shown inside wp-admin on update
Upgrade Notice 值得比平常更多的關注。這是大多數用戶在點擊更新之前看到的唯一文字:更新提示中的一兩行,解釋了為什麼此版本很重要。安全修復、重大變更、新的 PHP 要求。留空後,更新只是一個數字。
橫幅和圖示位於哪裡?
不進 readme.txt. 這幾乎第一次就會讓每個人都感到困擾,因為自述文件是所有其他清單內容的來源。
圖片生活在一個 /assets/ SVN 中的目錄,旁邊 trunk 和 tags,它們透過檔案名稱進行匹配:
| 文件 | 目的 | 尺寸 |
|---|---|---|
banner-772x250.png |
列出標題 | 772 x 250 |
banner-1544x500.png |
視網膜標頭 | 1544 x 500 |
icon-128x128.png |
搜尋結果圖示 | 128 x 128 |
icon-256x256.png |
視網膜圖示 | 256 x 256 |
screenshot-1.png |
第一個截圖 | 任何 |
螢幕截圖透過數字連接回自述文件。 screenshot-1.png 由下面第一行描述 == Screenshots ==, screenshot-2.png 到了第二個,依此類推。沒有匹配檔案的標題不會顯示任何內容;沒有標題的檔案顯示未標記的影像。
好的變更日誌是什麼樣的?
每個版本一個區塊,頂部最新,每行說明從用戶和#39; 的觀點來看發生了什麼變化:
= 3.2.5 =
* Fixed: admin menu order lost after a role change
* Improved: login customizer previews without saving
= 3.2.4 =
* Added: per-role dashboard widget visibility
&引用;錯誤修復和改進&引用;不告訴用戶任何事情,也不告訴評論者更少。變更日誌也是任何人決定是否信任您的插件首先出現的地方:穩定的特定條目清單讀作維護,兩年的間隔讀作放棄,無論程式碼是否仍然有效。
長變更日誌可以修剪。保留最近發布的版本 readme.txt 並將其餘部分移至 a changelog.txt;目錄讀取修剪後的目錄,歷史記錄保留在儲存庫中。
運送前檢查文件
機械檢查很快:確實如此 Stable tag 匹配存在的標籤資料夾,是否匹配 Version: 在您的插件標頭中,是 Tested up to 目前,是 150 個字元下的簡短描述,有五個或更少的標籤。
WordPress.org 有一個 官方自述文件驗證器 它解析文件並報告它無法讀取的內容,每個版本都值得運行一次。這 自述文件產生器 採取另一個方向:它從欄位建立文件,在其適用的欄位旁邊說明每個限制,預覽文件將產生的列表,並讀取現有內容 readme.txt 返回表單,以便舊插件 's 檔案可以更新而無需重新輸入。
如果您正在尋找其他人's 插件而不是發布您自己的插件,那麼 WordPress 外掛程式偵測器 列出了頁面加載的內容,以及 主題探測器 閱讀背後的主題。
