Community Information & Contributing
社群資訊與貢獻
````````````````````````````````
Ansible是一個開源項目,它被設計於讓開發者和管理員在共同構建自動化解決方案的時候更好的合作.
你想要參與進來嗎 – 不論是問問題,幫助其它使用者,像新人介紹ansible,或者幫助軟體和文件的完善,我們都非常歡迎你對這個項目的貢獻.
Topics
Ansible使用者¶
我有個問題¶
我們很樂意幫助你！
Ansible問題最好在Ansible的google談論組上面詢問.`Ansible Google Group Mailing List <http://groups.google.com/group/ansible-project>`_.
這裡有非常多的回答問題的列表和分享的技巧.任何人都可以加入進來,如果你只想線上閱讀的話,傳送郵件是可選的.為了減少垃圾郵件,儘管投遞很快就被批准,你的第一次投遞還是可能比較慢.
在問問題的時候,確保讓大家知道你執行的相關命令,輸出內容,一些細節,和你使用的Ansible版本
在需要的使用例項場合,儘量連結到 github 上展示,而不是在郵件列表中傳送附件.
推薦你在問問題之前使用 Google 搜尋,檢視是否相關問題已經被回答過了,但是如果在註釋中發現時間很久了,相關主題可能不再回復.
在問問題之前,確保使用的是最新的穩定版本的 Ansible ,你可以通過對比命令 ‘ansible –version’ 的輸出和 PyPi <https://pypi.python.org/pypi/ansible> 上面的版本來進行檢查.
同樣,你可以加入 IRC 頻道 - #ansible on irc.freenode.net .這也是一個很活躍的頻道, 如果還沒在郵件列表中沒有找到你想要的答案,因為郵件是非同步的,請暫停傳送郵件,你的郵件可能會引起核心開發人員的注意.
我想跟上版本釋出公告¶
版本通知釋出在 ansible 的項目上面,如果你不想跟上最新的郵件列表,你可以加入 Ansible 匿名郵件列表 Ansible Announce Mailing List
這是一個低流量的只讀郵件列表,我們指揮在這裡釋出版本通知和 可選的通向到 Ansible 大事件的連結
我想幫助分享和改善Ansible¶
你可以通過告訴朋友和同事,寫部落格,來把 Ansible 分享給其它人,或者出現在使用者討論組上面(像 DevOps組,或者本地 LUG)
你可以註冊一個免費的賬戶標記為 “Ansible”,在 speakerdeck 上面分享你的幻燈片.在推特上,你可以和 ansible 一起分享,或者跟隨我們 follow us.
我想讓Ansible開發的更快¶
如果你是一個開發者,最有價值的事情就是檢視 github issue 列表,幫助修復 bug.我們總是在特性開發時,優先考慮修復 bug 問題,因此你可以做的最好的事情就是清楚 bug .
如果你不是開發者,幫助測試提交的 bug 修復問題,也是很有價值的.你可以檢驗 ansible,在主分支下,開一個測試分支,合併 github 上的問題,測試,然後在指定的 issue 上面註釋.
我想報告 Bug¶
Ansible實際使用中暴露的問題 – 如果和安全相關,請發郵件到 security@ansible.com <mailto:security@ansible.com>,而不是發到 Google 討論組上面 .
有關核心語言的 Bug 應該被報道到 github.com/ansible/ansible <https://github.com/ansible/ansible> .在報告一個 Bug 之前首先檢查 bug/issue 檢視有關 issue 是否被報告了.
模組相關的 Bugs 應該基於模組的分類發到 ansible-modules-core <https://github.com/ansible/ansible-modules-core> 或者 ansible-modules-extras <https://github.com/ansible/ansible-modules-extras> .這會被列到模組文件的底部.
當你填bug資訊的時候,模組請使用 issue template <https://github.com/ansible/ansible/raw/devel/ISSUE_TEMPLATE.md> 提供所有相關的資訊,不管你正在填什麼類型的表格. (When filing a bug, please use the issue template to provide all relevant information, regardless of what repo you are filing a ticket against.)
知道你ansible的版本,和你執行的具體的命令,你期望什得到什麼結果,將會幫助我們和每個人世間,更快的知道問題.
不要使用類似,”我如何做(how do I do this)” 類型的問題.這裡都是 IRC 的參與者回答有用的問題,而不是討論有什麼問題的.學會提問.
尊重審稿人,使審稿人有時間幫助更多的忍,請提供 良好註釋,語言簡潔的playbook,包括playbook的片段和輸出內容.有用的資訊儘量提出來,省略無用的資訊
當在 playbook 分享 YAML 時候,格式可以被儲存通過使用 code blocks <https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks>
對於多檔案的內容,推薦使用 gist.github.com. 線上 pastebin 內容可能會過期,因此如果他們被長時間的引用,最好時間放久一點.(For multiple-file content, we encourage use of gist.github.com. Online pastebin content can expire, so it’s nice to have things around for a longer term if they are referenced in a ticket.)
如果你不確定你提供的是否為 bug,歡迎到 IRC 郵件列表提問一些相關的事情.
因為我們是一個大文獻的項目,如果你確定你有一個 bug ,請確保你開啟 issue ,確保我們有這個與你有關的issue記錄.不要依靠社群的其他人代替你上傳這個bug.
得到你的報告可能會花一些世間,具體資訊檢視下面的優先順序標識.
我想幫助改善文件¶
ansible 的文件也是一個社群項目.
如果你想幫助改善文件,糾正錯別字,或者改善一些章節,或者寫一個新特性的文件, 提交一個 github pull 請求,程式碼位於“docsite/rst” 子目錄,同樣也有一個 “Edit On Github”連線到哪裡的.
模組文件嵌入在源碼模組的底部,模組可能是 ansible-modules-core 或者 ansible-modules-extra 取決於在github上的模組.關於這的資訊一直列在網頁文件的每個模組底部
除了模組,主文件也在重建文字格式.(Aside from modules, the main docs are in restructured text format. )
如果你對新的重組的文字不滿意,你可以在 github 上開啟一個的標籤,關於你發現的錯誤,或者你想新增的部分.更多的資訊或者建立 pull 請求,請參考 github help guide.
對當前和未來的開發人員¶
我想學習如何在 Ansible 上開發¶
如果你剛開始使用 Ansible,想弄明白 Ansible 內部的工作機制,停止 Ansible-devel 郵件列表,像我們打個招呼,我們會帶你開始的.
一個好的開始方式可以是在模組網站上閱讀一些開發文件,然後找到一個 bug 然後修復,或者新增一些新的小特性.
模組最容易開始地方.
貢獻程式碼(特性或者修復bug)¶
Ansible 項目的原始碼託管在 github 上 ,核心應用位於 github.com/ansible/ansible ,還有兩個模組相關的子項目 github.com/ansible/ansible-modules-core. 如果你想知道一個模組是核心模組(“core”)還是額外模組(“extras”),查閱那個模組的網頁文件.
在提交程式碼之前,先到 ansible-devel 郵件列表討論一下特性問題,這可以有效的避免後期重複的工作.如果你不確定一個新的特性是否合適,先去開發郵件列表討論一下,這樣相對後來不得不修改一個 pull 請求更容易一些.
提交補丁的時候,一定要先執行單元測試“make tests”, 有一些基本的測試會自動運行當建立PR時候. 有更多的深入測試在測試/整合目錄,分為 destructive 和 non_destructive,執行這些如果他們屬於你的修改.他們被設定了標籤,這樣你就可以執行子集,一些測試需要雲憑證和只有他們提供的時候才會執行.當新增修復 bug 的新的特性的時候,最好新增新的測試防止後期重新回滾.
使用 “git rebase” vs “git merge”(讓git pull 別名為git pull -rebase 是一個好主意) ,來避免合併提交.也有一些基礎測試可以執行在 “test/integration” 目錄
為了保證歷史程式碼的整潔,和對新假如的程式碼做更好的審計,我們會要求那些包含合併註釋的重新提交.使用”git pull –rebase” 而不是 “git pull” 和 “git rebase” 而不是 “git merge”.同樣確保有主要分支在使用其他的分支的時候,這樣你才不會丟失註釋資訊.(Also be sure to use topic branches to keep your additions on different branches, such that they won’t pick up stray commits later.)
如果你犯錯了,你不需要關閉你的 PR ,建立一個清潔的本地分支然後推送到github上面使用 –force 選項,輕質覆蓋已存在的分支(在沒人使用哪個分支作為參考的情況下是允許的).程式碼註釋不會丟失,他們只是不會連線到現有的分支
然後我們將審閱你的貢獻和參與你的問題等等.
因為我們有一個非常大的和活躍的社群,我們可能需要一段時間才能看到你的貢獻,看一下後面的優先順序部分來了解一下我們的工作佇列.要有耐心,你的要求可能不會馬上合併,我們也讓 devel 能夠使用,因此我們需要小心的測試pull 請求,而這需要花費時間.
補丁應該一直在開發分支之上.
記住,小而專請求更容易檢查和接受,如果有例項,會更加幫助我們理解 bug 修復的工具和新的特性.
貢獻可以是新的特性,像模組,或者是修復一些你或其他人發現的 bug .如果你對寫新模組感興趣,請參考 module development documentation.
Ansible的理念鼓勵簡單、可讀的程式碼和 一致的,保守擴充套件, 向後相容的改進.程式碼開發Ansible需要支援Python 2.6 +, 而程式碼模組執行需要在Python 2.4之上.請使用4個空格的縮排,而不是tab,(we do not enforce 80 column lines, we are fine with 120-140. We do not take ‘style only’ requests unless the code is nearly unreadable, we are “PEP8ish”, but not strictly compliant.)
你也可以通過測試和修改其他請求貢獻,特別是如果它是一個你用著有趣的東西.請保持你的評論清楚和中肯,禮貌的和有建設性的, ticket 不是一個好開始討論的地方( ansible-devel 和 IRC 是專門為 tickets 的).
技巧：為了更容易的從一個分支執行,source ”./hacking/env-setup” 就這樣,不需要安裝.
其它主題¶
Ansible 職員¶
Ansible 一家支援Ansible和基於 Ansible 構建額外的解決方案的公司.我們會服務和支援那些有趣的東西.我們還提供了一個企業 web 前端 Ansible(見下面的 Tower ).
我們最重要的任務是使 ansible 社群發生一些大事,包括組織Ansible的軟體版本.想獲取更多的資訊,聯絡 info@ansible.com
在 IRC 上,你可以找到我們 jimi_c, abadger1999, Tybstar, bcoca.在郵件列表上,我們使用 @ansible.com 的地址傳送.
郵件列表資訊¶
Ansible有一些郵件列表,因為稽核的原因,你的第一次投遞郵件可能時間稍長,請允許一天時間的延遲.
Ansible Project List 分享 Ansible的技巧,問題解答,使用者討論.
Ansible Development List 學習如何在Ansible上開發,詢問ansible未來的設計特性,討論擴充套件ansible或者正在進行的ansible特性.
Ansible Announce list 關於ansible版本號的只讀共享資訊,小頻率的ansible事件資訊.例如：通知AnsibleFest的出現.
Ansible Lockdown List 關於ansible lockdown項目的所有資訊,包括DISA STIG 自動化和 CIS Benchmarks
對於非google賬戶訂閱一個組,你可以傳送郵件到這訂閱地址請求訂閱,例如：ansible-devel+subscribe@googlegroups.com
版本號¶
以 ”.0” 結尾的版本是朱版本,同時將會有很多新的特性.以其他整數結尾的 ,像”0.X.1” 和 “0.X.2”是小版本,這些僅僅包含 bug 修復
通常來說,我們不會發布小版本號(儲存用於大的項目),但是如果現在具體下次釋出會有很長時間的話,偶爾可能決定去除包含大量修復的小版本.
版本號基於沒有其他人使用 Van Halen 的歌曲命名.
Tower 支援問題¶
Ansible Tower <http://ansible.com/tower> 是一個對 ansible 提供的使用者介面,服務,應用程式介面等等.
如果你有關於 tower的問題,傳送郵件到 support@ansible.com <mailto:support@ansible.com> 而不是在IRC頻道上,或者一般郵件列表上提問
注意優先順序的標識¶
在2013年,Ansible 位於 github 上開源軟體的前 5 名,到目前為止,有 800 多個對此項目貢獻者,更不用說一個非常大的使用者社群,下載了這個應用超過一百萬次了.因此,我們有將會有很多的活動.
下面,我們會告訴你如何處理新來的請求的.
在我們的 bug traker 中你會注意到一些標籤- P1,P2,P3,P4和P5.這是我們的內部用於對提交的 bug 排序的.
除了一些例外,便於合併(比如文件類型), 我們都會首先花時間處理 P1 和 P2 item,包括 pull 請求.這些通常與重大的 bug 有關,同時影響大量的使用者群裡.因此,如果你看到一些 “P3 or P4 的分類,那些將不會得到立即的關注.
這些標籤沒有定義,它們只是簡單的排序.然而,有些東西影響核心模組(yum,apt,等等)可能會有更高的優先順序,相比那些影響少數使用者的模組來說.
因為我們非常強調測試和程式碼審查,可能需要幾個月的小功能合併.
但是不要擔心,我們也會定期的給迪有限的佇列做定期的清理,給予一些關注,由其在新模組的改變上面.因此,這不意味著我們把精力都花費在高優先順序的東西上,而忽略了你的 請求(ticket)
任何努力都會有幫助的,如果你促進快P3的 pull request 特性 ,你可以做的最好的事情是幫助處理 P2 bug 報告.