首页 > 其他, 分享, 常用功能 > 如何向社区提交问题 建议 bug patch 文档等等等

如何向社区提交问题 建议 bug patch 文档等等等

2013年9月26日     浏览数:2,923 发表评论 阅读评论

ATS社区的主要工作方式是以邮件和一些联动的提交系统组成的。成为这个社区的一员,要做的其实很简单,就是要跟大家交流。这个社区会欢迎任何人以任何角色参与交流:用户、测试工程师、开发工程师、学生。。。甚至竞争对手。Apache作为一个非常善于管理虚拟开源社区的组织,其文化能够保证交流的顺畅。你可以采用很多方面了解、参与ATS项目:

  • 官方新闻消息发布:
    官方新闻一般是通过邮件列表以及网站和blog等渠道发送出来:

    首页下部有重要新闻:http://trafficserver.apache.org/

    blog:https://blogs.apache.org/trafficserver/

  • 邮件列表,讨论一切问题:

    邮件列表注意:

    • 不要发附件,不要发html格式邮件,如果需要图片啥的,可以用pastebin类型的服务,再连进去
    • 尽量以英文发,如果实在难搞,发中文我们也可以帮你翻译
    • 不要在开发组问怎么用,在用户组为是不是bug等
    • 提问前确保已经看过文档,翻过google,查过邮件列表历史邮件
    • be nice, be patient
  • jira报bug、需求:

    jira是apache网站上报告bug、需求的重要平台,类似bugzilla等系统,开放注册,用户帐号系统独立运行。

    https://issues.apache.org/jira/browse/TS 是ATS的首页

    什么情况下需要提交jira:

    • bug:任何与期望不符的表现,都是bug
    • 任何情况下服务器crash掉都是严重bug
    • 需要优化、增强、提高、扩展等的是叫enhancement
    • 需要增加新功能的,叫 new feature

    如何提交一个有价值的jira?
    https://cwiki.apache.org/confluence/display/TS/Filing+useful+bug+reports

    如何让提交的信息更有助于大家分析问题?ATS是一个及其复杂的系统,复杂到非一个人所能够搞定所有问题,因此如果你碰到任何问题,请先提交到社区,同时进一步跟踪问题,直到找到问题的根源并解决。期间可能会有对这些问题比较清楚的人进进出出的帮你,如何才能让这些神仙眷顾于你呢,我们还是有一些好的建议的:

    • 首先要明确问题,并以相关关键词查过jira系统

    提交一个新issue,你需要有简明的标题,如:TS-306 enable log rotation for diags.log

    • 清楚的说明发生问题的环境,触发条件

    环境至少包含:TS版本,操作系统版本、平台,ATS的代理模式…

    • 有stack trace,GDB信息等
    • ATS在crash的时候,在Linux平台下,会打印出stack trace以利于后续的问题排查,这个功能默认是开启的,会在ts挂掉的时候打印出自己的调用情况到traffic.out中。常见的stack trace结果如下:
      FATAL: UnixNetVConnection.cc:799: failed assert `vio->mutex->thread_holding == this_ethread() && thread`
      /usr/bin/traffic_server - STACK TRACE:
      /usr/lib64/trafficserver/libtsutil.so.3(+0x13d77)[0x2aaaaaabfd77]
      /usr/lib64/trafficserver/libtsutil.so.3(+0x130ff)[0x2aaaaaabf0ff]
      /usr/bin/traffic_server(_ZN18UnixNetVConnection11set_enabledEP3VIO+0x45)[0x657c25]
      /usr/bin/traffic_server(_ZN18UnixNetVConnection8reenableEP3VIO+0x48)[0x65b0f8]
      /usr/bin/traffic_server(_ZN18UnixNetVConnection10do_io_readEP12ContinuationlP9MIOBuffer+0xa6)[0x6561d6]
      /usr/bin/traffic_server(_ZN21SSLNextProtocolAccept9mainEventEiPv+0x1fd)[0x64af1d]
      /usr/bin/traffic_server(_ZN18UnixNetVConnection11acceptEventEiP5Event+0x535)[0x659725]
      /usr/bin/traffic_server(_ZN7EThread13process_eventEP5Eventi+0xe7)[0x679aa7]
      /usr/bin/traffic_server(_ZN7EThread7executeEv+0xe1)[0x67a2d1]
      /usr/bin/traffic_server[0x678ad2]
      /lib64/libpthread.so.0[0x36ff607d15]
      /lib64/libc.so.6(clone+0x6d)[0x36ff2f248d]
      

      这个信息最好用c++filt转化为:

      FATAL: UnixNetVConnection.cc:799: failed assert `vio->mutex->thread_holding == this_ethread() && thread`
      /usr/bin/traffic_server - STACK TRACE:
      /usr/lib64/trafficserver/libtsutil.so.3(+0x13d77)[0x2aaaaaabfd77]
      /usr/lib64/trafficserver/libtsutil.so.3(+0x130ff)[0x2aaaaaabf0ff]
      /usr/bin/traffic_server(UnixNetVConnection::set_enabled(VIO*)+0x45)[0x657c25]
      /usr/bin/traffic_server(UnixNetVConnection::reenable(VIO*)+0x48)[0x65b0f8]
      /usr/bin/traffic_server(UnixNetVConnection::do_io_read(Continuation*, long, MIOBuffer*)+0xa6)[0x6561d6]
      /usr/bin/traffic_server(SSLNextProtocolAccept::mainEvent(int, void*)+0x1fd)[0x64af1d]
      /usr/bin/traffic_server(UnixNetVConnection::acceptEvent(int, Event*)+0x535)[0x659725]
      /usr/bin/traffic_server(EThread::process_event(Event*, int)+0xe7)[0x679aa7]
      /usr/bin/traffic_server(EThread::execute()+0xe1)[0x67a2d1]
      /usr/bin/traffic_server[0x678ad2]
      /lib64/libpthread.so.0[0x36ff607d15]
      /lib64/libc.so.6(clone+0x6d)[0x36ff2f248d]
      
    • 当然,这些简单的stack trace结果是不够的,请参考上面启用core的方法,抓到core文件后再进一步gdb跟踪,并提供相应的更详细信息

    • 如果有测试用例,那就更好了

    我们已经有一个非常棒的开源功能测试框架,https://github.com/ZongYi-Ali/Macaroon

    • 随时补充其他人需要你提供的信息

    交互过程中,更能学到更多信息

    开发也会使用cwiki来纪录一些FAQ,以及项目性质的中间文档
    https://cwiki.apache.org/confluence/display/TS/Apache+Traffic+Server

    如:https://cwiki.apache.org/confluence/display/TS/Projects 纪录了所有正在做的大模块问题、计划、进展情况等。
    https://cwiki.apache.org/confluence/display/TS/Releases 纪录了后续版本的roadmap规划等

  • irc直接找人:
    去 #traffic-server on irc.freenode.net.

  • 本地社团:

  • 开发相关:

    开发人员一定要熟悉一些东西:

    如何提交一个patch?

    • 确保自己已经pull了官方最新master分支代码

    git repo有很多:

    • 官方committer用,可以提交的:https://git-wip-us.apache.org/repos/asf/trafficserver.git 这个也可以同时用作公用的。
    • 公众用的,只可以pull的:
      • http://git-wip-us.apache.org/repos/asf/trafficserver.git
      • git://git.apache.org/trafficserver.git
      • github
        地址:http://github.com/apache/trafficserver
        这里又是一大坨repo地址,这github是apache的一个镜像点,不作为提交点

    新clone可以用: git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git

    https://git-wip-us.apache.org/repos/asf/trafficserver.git

    • 修改代码,并提交
    • 用任何你需要的方法修改并提交代码
    • 并写一个非常清楚的一行说明

      这个一行的说明,以TS-xxx:开头,能够清楚描述patch做的工作,并不要太长,如不要超过80字符

      例如:TS-2187: use nonblock eventfd in EventNotify

    • 以及详细的多行说明

      一个详细的说明,篇幅可以长很多,一定要有调理的列出相关的变化的原因与目的,以及由此引入的配置、接口变化,同时列出必要的示例。

    • 参见下面的一个非常好commit例子:

      commit 9a6fc2ab6b3147e82dfc229a7158083371d5545e
      Author: Yunkai Zhang <qiushu .zyk@taobao.com>
      Date:   Sun Sep 8 23:35:39 2013 +0800
      
          TS-2187: use nonblock eventfd in EventNotify
      
          1) Use nonblock eventfd, so that we can tolerate write() failed with
              errno EAGANIN – which is acceptable as the signal receiver will be
              notified eventually in this case.
      
          2) After using nonblock eventfd, read() will not block in wait(). So
              I use epoll_wait() to implement block behavior, just like timedwait().
      
          3) nonblock eventfd can fix a potential problem: if receiver didn't
              read() data immediately, senders might block in write().
      
          Signed-off-by: Yunkai Zhang </qiushu><qiushu .zyk@taobao.com>
      
    • 检查自己的邮箱等信息是否设置正确

    尽管一个日常使用git的用户,肯定都已经设置好了名字和邮箱,我们建议大家提交patch的时候多检查一下,参见上面的例子里:Author: Yunkai Zhang ,有一个一致的名字对后续大家认识你非常重要,有一个体现公司的邮箱,可以将你的荣誉同时归功于你与你的雇主,开源社区我们能够回馈的就是这些credit啦!

    • 提炼出patch

    我们的代码已经commit到自己本地repo后,可以用 git format-patch命令生成

    zymMBPr:traffic.git zym$ git status
    # 位于分支 master
    # 您的分支领先 'apache/master' 共 1 个提交。
    #   (使用 "git push" 来发布您的本地提交)
    #
    # 未跟踪的文件:
    #   (使用 "git add <file>..." 以包含要提交的内容)
    #
    #   test/
    #   tmp/
    提交为空,但是存在尚未跟踪的文件(使用 "git add" 建立跟踪)
    zymMBPr:traffic.git zym$ git show
    commit 4db9faf3975891cc3df7fc42d8dd9072af22c4ed
    Author: Zhao Yongming <ming .zym@gmail.com>
    Date:   Tue Aug 20 18:24:31 2013 +0800
    
        doc: update cluster howto to for connections
    
    diff --git a/doc/admin/cluster-howto.en.rst b/doc/admin/cluster-howto.en.rst
    index 612db32..3b01019 100644
    --- a/doc/admin/cluster-howto.en.rst
    +++ b/doc/admin/cluster-howto.en.rst
    @@ -135,8 +135,8 @@ Performance tweak for busy Cluster
     ==================================
    
     Starting from v3.2.0, Apache Traffic Server can handle multiple internal
    -cluster connections, and we can tweak for the Cluster threads and
    -connections:
    +cluster connections, and we can tweak for the Cluster threads and each of
    +the thread will keep one connection to all of the cluster machines:
    
     -  Increasing Cluster threads:
    
    @@ -147,13 +147,8 @@ connections:
    
     .. XXX::  ET_NET and ET_CLUSTER should be documented some place. Right now, this means nothing to me.
    
    --  Setup the Cluster connections:
    -
    -   In the Cluster, the internal connections is TCP and limited by
    -   ET_CLUSTER threads and network performance, we can increase the
    -   connections to archive better performance.::
    -
    -       traffic_line -s proxy.config.cluster.num_of_cluster_connections -v 10
    +   ::
    +       traffic_line -s proxy.config.cluster.threads -v 10
    
     with these tweaks, we can archive about 10gbps traffic for the internal
     cluster transfer speed.
    zymMBPr:traffic.git zym$ git log | head
    commit 4db9faf3975891cc3df7fc42d8dd9072af22c4ed
    Author: Zhao Yongming </ming><ming .zym@gmail.com>
    Date:   Tue Aug 20 18:24:31 2013 +0800
    
        doc: update cluster howto to for connections
    
    commit 1ec3990bf7c30b8a50764dce16d819ba76180a0d
    Author: Yu Qing <zhuangyuan @taobao.com>
    Date:   Mon Sep 16 10:26:27 2013 +0800
    
    zymMBPr:traffic.git zym$ git format-patch 1ec3990bf7c30b8a50764dce16d819ba76180a0d
    0001-doc-update-cluster-howto-to-for-connections.patch
    zymMBPr:traffic.git zym$ cat 0001-doc-update-cluster-howto-to-for-connections.patch
    From 4db9faf3975891cc3df7fc42d8dd9072af22c4ed Mon Sep 17 00:00:00 2001
    From: Zhao Yongming <ming .zym@gmail.com>
    Date: Tue, 20 Aug 2013 18:24:31 +0800
    Subject: [PATCH] doc: update cluster howto to for connections
    
    ---
     doc/admin/cluster-howto.en.rst | 13 ++++---------
     1 file changed, 4 insertions(+), 9 deletions(-)
    
    diff --git a/doc/admin/cluster-howto.en.rst b/doc/admin/cluster-howto.en.rst
    index 612db32..3b01019 100644
    --- a/doc/admin/cluster-howto.en.rst
    +++ b/doc/admin/cluster-howto.en.rst
    @@ -135,8 +135,8 @@ Performance tweak for busy Cluster
     ==================================
    
     Starting from v3.2.0, Apache Traffic Server can handle multiple internal
    -cluster connections, and we can tweak for the Cluster threads and
    -connections:
    +cluster connections, and we can tweak for the Cluster threads and each of
    +the thread will keep one connection to all of the cluster machines:
    
     -  Increasing Cluster threads:
    
    @@ -147,13 +147,8 @@ connections:
    
     .. XXX::  ET_NET and ET_CLUSTER should be documented some place. Right now, this means nothing to me.
    
    --  Setup the Cluster connections:
    -
    -   In the Cluster, the internal connections is TCP and limited by
    -   ET_CLUSTER threads and network performance, we can increase the
    -   connections to archive better performance.::
    -
    -       traffic_line -s proxy.config.cluster.num_of_cluster_connections -v 10
    +   ::
    +       traffic_line -s proxy.config.cluster.threads -v 10
    
     with these tweaks, we can archive about 10gbps traffic for the internal
     cluster transfer speed.
    --
    1.8.4
    
    zymMBPr:traffic.git zym$
    

    这里的 0001-doc-update-cluster-howto-to-for-connections.patch 就是我们可以提交到jira里的patch。社区的多数人都认为:

    • 一次性提交很多patch是不好的,review的压力很大
    • 一个patch改很多方面的东西是不好的,容易出错,并没有人愿意review大patch
    • 使用多个小的patch远比一个大而烦的patch要nice的多
    • 类似变量改名、缩进修改等,需要放在大版本发布前后搞,并跟大家商量一下
      • 提交到相应的jira issue里
    • 必要的话,在jira里再详细说明,我们不怕烦,就怕看不明白
      • 把issue设置为patch avalible
    • 这样就会有人给你review啦
    • 提交上来的patch大家会review并给出反馈,如果希望patch能为社区接受,必须要有一个虚心开放的心态接受大家的评价和有理无理要求,能够接受并改进是社区合作的基础。
    • 因为功劳归于作者,多数帮你review和帮你提交代码的committer都不会帮你改代码,只会给你建议,多数情况大家都比较nice,把对方的建议当成must,如果很难说服自己妥协,就列出相应的原因。
    • 理越辩越明,不要怕反复,不要怕别人纠缠。committer之间吵架的时候比给新人review评价要凶的多。
    • 根据reviewer的建议改进,是社区评价合作一个重要方面:D
  • 用户材料:

    官方的文档,必须看吧:http://trafficserver.apache.org/docs/
    官方的wiki,也得找找,尤其是FAQ:https://cwiki.apache.org/confluence/display/TS

Apache的社区,会绝对避免被一个公司或小团体把持,因此在社区里的各种投票制度非常普遍,ATS也是严格遵守相关的bylaws,https://www.apache.org/foundation/bylaws.html 欢迎以任何身份参与ATS项目的日常工作中来,您的意见都会被严肃对待的。

分类: 其他, 分享, 常用功能 标签:
  1. 本文目前尚无任何评论.
  1. 本文目前尚无任何 trackbacks 和 pingbacks.