如何發佈一個Atom的package

原文是寫在簡書上面的， 我如今搬過來了，這邊更新會稍慢點。

http://www.jianshu.com/p/98f99c20493c

上次爲你們介紹了package.json的內容，文件在nodejs是很是有用的，發佈npm是必須使用的，那麼此次給你們說說如何給github的親兒子編輯器Atom發佈一個package，以便於共享你的好工具，造福你們。

簡單介紹下Atom，是github用nodejs編寫的一個編輯器，其實應該主要使用了node-webkit的技術，若是感興趣，能夠下次給你們詳細分析。

此文章來源於官方文檔的翻譯和本身開發插件的一些心得 ---- https://atom.io/docs/v1.2.4/hacking-atom-package-word-count

Package Generator

建立一個package最簡單的方式就是使用atom裏面的生成器，使用命令面板--command(window)+shift+P,輸入generator，找到Package Generator:Generate Atom Package 這行命令，選擇便可，這個時候輸入你的package名字，能夠起一個高大上有逼格的名字。

看見atom幫你建立了一大堆的文件夾和文件，通常來講，基礎包以下

my-package/
      keymaps/
      lib/
      menus/
      spec/
      styles/
      package.json
  README.md
  CHANGELOG.md
  LICENSE.md
  .gitignore

package.json

一樣，首先看 package.json  由於他涉及到你的發佈和各類配置。跟npm的很像，可是有本身的東東

•  main ： 這個是你執行命令後進入的主文件，也就是入口文件，默認是尋找index的，同時atom支持 coffee 和 js

• styles ：一個字符串數組聲明來讓atom加載樣式文件順序，若是沒有，就順序的讀取styles文件夾裏面的文件。

• keymaps ： 一個字符串數組聲明package須要加載的key map文件順序，若是沒有，按順序讀取keymaps文件夾的文件。

• activationCommands ：一個對象來聲明觸發你的package的行爲，key是css選擇器形式，value是一個字符串數組聲明命令。知道規定的css 選擇器中一個觸發了，纔會載入你的package。

來看看下面的package.json長相：

{
      "name": "my-package",
      "main": "./lib/my-package",
      "version": "0.0.0",
      "description": "A short description of your package",
      "keywords": [
        ],
      "activationCommands": {
        "atom-workspace": "my-package:toggle"
        },
        "repository": "https://github.com/atom/my-package",
        "license": "MIT",
        "engines": {
          "atom": ">=1.0.0 <2.0.0"
        },
        "dependencies": {
        }
    }

你最早要確認的事情是就填寫這些信息，包括：name，description, repository， license。 剩下的能夠邊作邊寫。

Source Code

咱們來看看咱們主文件，也就是剛剛建立的my-package.coffee,若是你在package.json中main的屬性沒有填寫，就是用index文件了，這跟瀏覽器解析url很類似。

這跟最高級別的模塊是一個單獨對象，管理着你的package在atom的生命週期，不管你有其餘多少的視圖和模塊，都被它管理。

看看這個模塊有哪些重要的方法：

• activate(state): 這個必需的方法在你的package執行的時候被調用，若是你的模塊使用了serialize()方法，那麼這個方法會傳遞狀態數據，在你最後一次窗口被序列化的時候。使用這個初始化工做流程在package開始時

• serialize() ：這個可選的方法在窗口被掛起的時候調用，容許你返回一個json表示你的組件狀態。當窗口再次喚起的時候，這個數據會傳遞給activate方法，這樣你就能夠恢復你的視圖。

• deactivate() ：這個可選的方法也是被掛起的時候調用，若是你的package有監放任何文件或者保持外部的資源，釋放他們在這個時候。若是你只是訂閱窗口內的，就沒必要關心了。

Style Sheets

這個很簡單，就是你的package執行的時候，用到的樣式表而已，能夠是css或者less。less更好，比較推薦。

其實你不須要太多的css，由於atom自己就提供了一個標準包給使用，你可使用CMD+shift+P 而後 搜索 styleguide 或者 cmd+crtl+shift+G。

若是你有什麼特別要求，可使用這個style文件夾，記得添加package.json的路徑。

Keymaps

推薦使用經常使用的操做鍵來綁定擴展，特別是你也新加了一個命令的時候，在咱們package裏面，咱們的keymaps/my-package.cson文件：

'atom-workspace':
    'ctrl-alt-o': 'my-package:toggle'

這個意思就是你同時按下 crtl-alt-o的時候，咱們的package就會執行toggle命令，你能夠更改這些綁定在這個文件。

全部的快捷鍵都在keymaps的文件目錄中，默認是全部的文件都被載入的，package.json文件中有個可選的keymaps選項能夠指定哪些文件被載入

Menus

這個文件主要是定義菜單欄的，包括頂部的package菜單裏面的選項，和右鍵菜單選項。和keymaps同樣能夠在package.json裏面配置指定文件。

而後就是開發咱們的插件，這個比較複雜，主要是涉及到Atom內部的各類API和機制，此次先不講，先說其餘的。

Basic Debugging

最簡單的就是使用 console.log 來調試，跟咱們在瀏覽器同樣，由於node-webkit其實就一個瀏覽器。

使用alt-cmd-I 或者選擇菜單 View>Developer> Toggle Developer Tools

Testing

固然咱們還須要寫測試功能，全部的測試代碼在 spec目錄下面，使用jasmine來測試，因此你們要熟悉下jasmine的語法，其實各類測試都差很少。

使用cmd-alt-ctrl-p或者Developer>Run Package Spec菜單開始執行測試。通常來講都會有錯誤，以下所示：

你能夠本身慢慢的修改測試代碼，保證經過，同時保證本身的package代碼不錯。

Publishing

如今咱們的package沒問題了，也測試經過了，剩下的就是發佈了，要注意一些小的細節，要不發佈極可能失敗。

Prepare Your Package

• package.json 必定要有 name， description 和 repository字段

• package.json 要有 version字段來表示版本號" 0.0.0"

• package.json 會有 engines 來表示工做環境，通常就是 {"Atom":">=1.0.0 <2.0.0"}

• 要有一個README.md文件在根目錄

• 整個文件要在github上有本身的地址，而且已經提交

Publish Your Package

在你發佈以前，最好去atom官網上找找會不會有跟你同名的package，若是有，你就只能修更名字，確保沒有以後， 你就能夠在你的目錄下 使用

apm publish minor

來發布你的package了

這個命令會作如下事情：

1. 註冊一個package的名字在atom.io上，若是是第一次發佈

2. 更新version從package.json文件中，而後提交

3. 建立一個新的 git tag 給此次提交

4. 推送這個tag和分支到 github上

5. 用新發布的version更新到 atom.io 上

若是你是第一次提交，可能會須要填寫你github的用戶名和密碼，這個你跟着guide走就好了，注意別填錯了，主要是數字別用小鍵盤。

term中顯示成功以後，你就能夠在

https://atom.io/packages/my-package

看到你的package的頁面了。記得編寫README.md的內容給你們看。

說說 minor這個意思，其實publish後面跟的參數有三個選項的。

• major： 表示給 apm 增長版本號的第一個數字，1.0.0 這樣子 git tag 也會是 v1.0.0

• minor： 第二個數字， 0.1.0的含義

• patch： 最後一個數字， 0.0.1的意思

這個是跟版本號管理對應的，通常數來 major對應是日後兼容性的改變，例如 修改默認設置或者刪除功能， minor 通常就是添加一個小功能或者優化。 patch 就是修復小的bug。

以上就一個完整的atom package開發和發佈的過程，主要參考官網的文檔，裏面有我必定的心得。

同時，介紹個人新插件 https://atom.io/packages/vue-format

主要是最近開始寫 vue.js，而後webpack打包，使用.vue的文件方式，結果沒有能格式化文件的插件，因此給atom寫了一個，這是 0.1.0的版本，有問題很正常，我後面還會慢慢優化，若是你們有興趣，能夠一塊兒來優化，或者給我提各類issue，歡迎交流