如何为开源项目和社区做贡献 -- 你应该知道的十件事(四)——如何创建自己的开源项目?

问题四:如何创建自己的开源项目?

  在前文中,我们已经介绍了最常见的给开源项目做贡献的两种途径,但随着你做开源项目的深入,你可能就会发现一个新的方向并推出自己的开源项目,下面,我将结合我的讲演,向大家分享一下创建开源项目的经验。

1. 学习成功的开源项目

  在GitHub上,有很多优秀的开源项目,对于新入门开源项目的小伙伴来说,学习并模仿一些成功的开源项目是十分必要的,主要学习以下内容:

  • 项目命名格式,包括项目名称、文件夹名称等等。
  • 文件夹结构,模仿与你所做项目比较相似的项目,学习一下人家是如何组织文件结构的。
  • README文件撰写,学习一下成功的项目他的项目README文件时如何组织的。
  • 编程规范,开源项目要有很好的编码规范以及一致的代码风格,可以学习一下开源项目所使用的编程规范。

  以上只是罗列了一些比较重要的内容,需要学习的内容还有很多,学习永远在路上。最好是能够将集百家之长,然后形成自己的风格,这样就可以在自己的各个项目中使用,下次再创建新的项目时直接套用模板即可。

2. 固定自己的模板

  通过学习一些优秀的开源项目,我们可以找到这些项目的共性,然后结合自己的风格,形成自己的模板。通过我创建开源项目的经验,可以很明确的告诉大家,一定要找到一个或者是固定一个适合自己的模板,这对自己后续创建项目以及维护项目是十分重要的。在固定自己模板时,应重点关注以下几点:

  • 项目结构:这一块主要是一个文件结构,在创建项目时,你要考虑一下你的项目都有哪些内容,需要那些文件夹,哪些内容放在哪个文件夹里,这些内容如果你一开始没有考虑好,后续调整会十分麻烦。
  • 编程风格:这是十分重要的一块内容,做开源项目,一定要遵循开源代码风格,现在比较常见的是谷歌代码风格,你可以结合谷歌代码风格,然后根据自己的编程习惯,形成一套自己的编程风格。
  • 文件格式:抛开代码文件不说,主要的就是技术文档文件,开源项目一定要使用Markdown(.md)格式文件,尽量不使用第三方插件;此外就是技术文档格式一定要规范,层次分明,如果项目比较关键的话,要有中英文版本。

  通过模仿成功的开源项目,这样你就可以开始创建自己的开源项目了,相面我将会在此处讲讲开源项目中的几个关键内容。

3. README.md 撰写

  首先是撰写README,当然这项工作是你已经完成了厂库搭建以及代码内容后进行的,属于项目的收尾阶段进行的工作。但是这确实极其重要的一步,README是对你项目的介绍,也是对外展示你项目的主要窗口,因此README文件的第一印象就会决定访问者对你的项目是否感兴趣,因此既要有实用的内容,也要做的好看。

  此处我总结了一些README文件的撰写经验,首先第一点是README要包含哪些内容,主要有以下方面:

  • 项目简介:在README的顶部,用简洁的语言描述你的项目是什么,做什么,以及为什么有用,这可以帮助读者快速了解项目的核心概念和目的。
  • 项目徽章:使用徽章来展示项目的状态,如构建状态、代码质量、许可证等,这些徽章可以提供额外的信息,并增强项目的专业性。
  • 安装和使用说明:提供清晰的安装和使用说明,包括必要的依赖项、配置步骤和示例代码,确保这些说明足够详细,以便新用户能够轻松地开始使用你的项目。
  • 功能亮点:突出显示你的项目的主要功能和特性,以及它们如何解决用户的问题或需求。这有助于吸引潜在用户并展示项目的价值。
  • 屏幕截图和演示:如果可能的话,添加屏幕截图、GIF动画或视频演示,以展示项目的实际效果和用法,这可以使你的项目更直观易懂,并激发用户的兴趣。
  • API文档或链接:如果你的项目提供了API,确保在README中包含相关的API文档或链接。这可以帮助开发人员更好地理解和使用你的项目。
  • 贡献指南:提供一个贡献指南,说明如何参与项目的开发、提交代码更改、报告问题等。这有助于建立一个积极的社区氛围,并鼓励其他人参与你的项目。
  • 许可证:在README中明确指出项目的许可证类型,并提供许可证文件的链接。这可以确保用户了解他们使用你的项目的条件和限制。
  • 联系方式:提供你的联系方式(如电子邮件、Slack频道等),以便用户或其他开发人员与你取得联系、提出问题或寻求支持。

  以上这些内容看起来比较多,如果放在一个文件里,就会显得十分冗余,所以对于一些比较大型的项目,可以将其中的一部分包含详细内容的部分放置在另一个文件中,然后在README文件中提供条目以及链接,这样使用人员可以很容易找到相关的文档。

  除了内容要全面之外,README还要做的美观、大气以及有条理,能够吸引人眼球,因此,你还要学习一下README文件的美化。其实对于我们程序员来说,README文档的美化并不是做的要多么花里胡哨,只要做的规整、清晰有条理即可,因此要善于使用小图标、标题等级等内容,让你的README文件变得十分有条理。

  另外,为了更好地推广你的开源项目,你最好提供的README文件包括英文版以及中文版,这样对于一些其他国家的开发者也可以明白如何使用。下面链接是我推出并维护的一个开源项目的README文件,,该文件我也是在不断学习与改进中,仅供参考:

https://github.com/guojin-yan/OpenVINO-CSharp-API/blob/csharp3.0/README.md

4. CONTRIBUTING.md

  CONTRIBUTING文件是一个重要的文档,用于指导贡献者如何参与项目的开发和贡献,它包含了一系列准则、规则和建议,以确保贡献者能够顺利地参与项目,并且保持代码库的质量和一致性。下面简单介绍一下CONTRIBUTING主要包含哪些内容:

  • 欢迎和介绍:在文件的开头,用友好的语言欢迎贡献者,并简要介绍项目的目标和背景。说明贡献的重要性,以及你期待的贡献类型。
  • 行为准则:为你的项目制定一个行为准则,定义在项目中可接受和不可接受的行为。这有助于维护一个积极、尊重和支持的社区氛围。确保明确说明如何处理违规行为和报告问题的途径。
  • 贡献流程:详细描述贡献的流程,包括如何提交问题、提出功能请求、创建拉取请求等。提供清晰的步骤和示例,以便贡献者能够轻松参与项目的开发。
  • 编码规范和风格:定义项目的编码规范和代码风格要求,以确保代码的一致性和可读性。提供相关的文档或链接,以便贡献者了解并遵循这些规范。

以上就是一个简单的CONTRIBUTING内容,对于我们个人创建的小型项目来说,这已经足够使用了。

问题五:开源社区中的道德规范

  虽然开源社区是自由的,但是它也有一些规则和准则需要遵守。这些规则和准则是为了确保社区的秩序和协作的顺利进行。例如,尊重他人的贡献、保持礼貌和尊重、遵守项目的许可协议等。这些规则和准则有助于维护一个积极、健康和协作的社区环境。所以在此处我重点重复一下在开源社区中所需要遵守的一些进本的道德规范。

  • 第一点:检查重复
      这里的重复包含很多内容,例如问题重复、项目重复、PR重复、文章重复等等。

    • 首先讲一下问题重复。假设您在本地计算机上安装并运行一个开源项目,但遇到了一个错误。或者您通读了文档并发现了缺失的步骤,您可能想提出一个问题来解决这个问题。但在执行此操作之前,必须检查是否提出了类似的(打开和关闭)问题或拉取请求,以避免重复。在 GitHub 上问题或拉取请求页面顶部的搜索栏中输入可能的关键字,以检查是否存在可能的重复。
    • 然后是项目重复。如果你有一个新的想法,准备大干一场,创建一个新的开源项目,你首先要做的第一点就是检查一下当前是否有人在做相同的开源项目。可以通过GitHub的关键字检索,查找类似的项目,看看你的想法是否有人已经做过了。如果有人已经做过了,你可以检查一下他所做的项目与你要做的有什么差异,你所做的项目内容可能是对他项目的改进、升级等。这样的话,如果你需要创建一个新的项目,你最好可以跟原作者进行沟通,表明自己的想法,然后再创建时进行使用别名。
    • 接着就是PR重复。如果你发现开源项目的一些问题你是能够解决的,这时你就需要通过提交PR的方式进行提交,但是在提交前,你需要做一步检查,第一点检查一下该问题是否有人已经领取,如果有人领取,但是领取人长时间没有提供回复、提供的PR你觉得存在问题或者你有更好的解决思路,那这样的话你可以在问题下留言,申请提交自己的PR。
    • 最后是文章重复,这里可以是技术文章或者是博客文章。但是,文章重复是禁止的,因为文章重复会被认为是抄袭,你可以有部分是重复的,例如技术介绍,这些不是关键部分内容,但是对于关键部分,一定不能重复。另外如果你觉得该文章比较好,你可以申请转载,在转载时注明文章来源即可。
  • 第二点:行为礼貌和尊重
      在开源社区,一定要学会尊重和礼貌,在请教或者回复别人时,一定要有礼貌并尊重他人。首先是再请教别人时,一定要先表示感谢,然后要全面地展示一下自己的问题,最后再次表示感谢,在话语中一定要礼貌。另外在回复别人问题时,也要保持一种谦卑的语气,闻道有先后,术业有专攻,所以并没有什么优越感,要认可和尊重他人的工作成果和贡献,无论是代码、文档、设计还是其他形式的贡献,在适当的场合给予他人认可和赞誉。最后就是在自己的文章中也要保持基本的礼貌,不要含沙射影,不要谈论政治,不要涉及政治、宗教或其他具有争议性的话题,专注于项目的目标和愿景,确保所有人都能在一个中立的环境中参与和贡献。

  • 第三点:协作和分享
      首先是要学会帮助他人,如果你看到有人需要帮助或提问,尽量提供帮助。因为开源社区大佬很多,你帮助了他,在未来他可能也会帮助你,而且付出总会有回报,因此不要吝啬自己的帮助。另外要学会分享知识与经验,积极与社区成员分享你的经验和知识,你所经历的事情在未来别人可能也会经历,因此学会把你的经验分享出去,避免更多人踩坑。

  • 第四点:保证质量和追求卓越
      高质量的项目更容易获得用户和开发者的信任,当用户知道项目维护良好、少有bug,他们更愿意使用和推荐这个项目,这种信誉是开源项目成功的关键因素之一。并且随着项目质量的提高,用户基础和社区规模往往也会增长,质量高的项目更有可能持续发展,因为它们提供了一个稳固的基础,可以在其上构建新功能和改进。因此,我们要学会保证质量和追求卓越。

    • 首先,要制定清晰的贡献指南,说明如何提交贡献、代码风格、测试要求等,帮助维护代码质量和一致性。实行代码审查制度,让其他开发者检查新的提交,以发现潜在的错误、改进代码质量,并确保新代码符合项目的标准。并且利用自动化测试来确保代码改动不会破坏现有功能。这包括单元测试、集成测试、系统测试和性能测试。
    • 其次,就是提供详尽的文档,包括安装指南、使用教程、API文档和开发者指南,让用户和开发者容易理解和使用项目。并且使用问题跟踪系统来管理bug报告和功能请求,保证所有问题都被记录和跟踪,使用版本控制系统如Git,并采取适当的分支策略来管理代码的不同版本和功能开发。
    • 最后就是鼓励和促进社区成员之间的交流,通过讨论和协作来提高项目质量,要学会认可社区贡献者的工作,提供激励措施(如贡献者列表、感谢信等),以鼓励更多高质量的贡献。如果可以的话,可以提供开发者指南、教程和其他教育资源,帮助新成员更快地上手,并提升整个社区的技术水平。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/592528.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

Linux 命令echo

命令作用 输出一行字符串在shell中,可以打印变量的值输出结果写入到文件在显示器上显示一段文字,起到提示的作用 语法 echo [选项] [字符串] 参数 字符含义-n不自动换行-e解释转义字符-E不解释转义字符 如果-e有效,则识别以下序列&…

SpringBoot 项目如何生成 swagger 文档

推荐使用 springdoc-openapi 的理由 1、springdoc-openapi 是 spring 官方出品,与 springboot 兼容更好(springfox 兼容有坑) 2、springdoc-openapi 社区更活跃,springfox 已经 2 年没更新了 3、springdoc-openapi 的注解更接近 …

力导向图与矩阵排序

Graph-layout force directed(力导向图布局)是一种用于可视化网络图的布局算法。它基于物理模型,模拟了图中节点之间的相互排斥和连接弹性,以生成具有良好可读性和美观性的图形布局。 在力导向图布局中,每个节点被视为…

(一)Matlab数值计算基础

目录 1.1Matlab命令组成 1.1.1基本符号 1.1.2功能符号 1.1.3常用命令 1.1Matlab命令组成 1.1.1基本符号 #提示运算符,表示软件处于准备就绪状态。在提示符号后输入一条命令或者一段程序后按Enter键,软件将给出相应的结果 >> *…

基于SpringBoot的影院订票系统

文章目录 项目介绍主要功能截图:部分代码展示设计总结项目获取方式🍅 作者主页:超级无敌暴龙战士塔塔开 🍅 简介:Java领域优质创作者🏆、 简历模板、学习资料、面试题库【关注我,都给你】 🍅文末获取源码联系🍅 项目介绍 基于SpringBoot的影院订票系统,java项目…

牛客练习赛50-C

题目描述 在一个游戏中,tokitsukaze需要在n个士兵中选出一些士兵组成一个团去打副本。 第i个士兵的战力为v[i],团的战力是团内所有士兵的战力之和。 但是这些士兵有特殊的要求:如果选了第i个士兵,这个士兵希望团的人数不超过s[i]…

【Proteus仿真】【Arduino单片机】汽车尾气检测报警系统

文章目录 一、功能简介二、软件设计三、实验现象联系作者 一、功能简介 本项目使用Proteus8仿真Arduino单片机控制器,使用按键、LCD1602液晶、蜂鸣器模块、CO、NOx、HC和PM2.5气体传感器等。 主要功能: 系统运行后,LCD1602显示CO、NOx、HC和…

手机录屏没有声音?让你的录屏有声有色

“有人知道手机录屏怎么录声音吗?今天录制了一个小时的直播视频,后面查看的时候发现没有声音,真的非常崩溃,想问问大家有没有办法,解决这个问题。” 在手机录屏的过程中,有时候我们可能会面临录制视频没有…

使用 Spectrum LSF 设置多集群和作业转发

使用 Spectrum LSF 设置多集群和作业转发 以下示例是有关如何使用 Spectrum LSF设置多集群和作业转发的指南。 此示例说明了集群是本地集群,另一个在云中的常见情况。 此示例假定标注为 “OnPremiseCluster” 的内部部署集群使用子网 192.168.0.0/24 ,…

Spring技术内幕笔记之IOC的实现

IOC容器的实现 依赖反转: 依赖对象的获得被反转了,于是依赖反转更名为:依赖注入。许多应用都是由两个或者多个类通过彼此的合作来实现业务逻辑的,这使得每个对象都需要与其合作的对象的引用,如果这个获取过程需要自身…

奇因子之和(C语言)

题意: 一个整数的因子,就是所有可以整除这个数的数。奇数指在整数中,不能被 2 整除的数。所谓整数 Z 的奇因子,就是可以整除 Z 的奇数。 给定 N 个正整数,请你求出它们的第二大奇因子的和。当然,如果该数只…

Amazon API Gateway CORS 实战

Amazon API Gateway提供了一种实现跨域资源共享(CORS)的方式,以便在Web应用程序中安全地使用API。下面是Amazon API Gateway CORS的实战指南: 创建一个API Gateway REST API并定义资源和方法。在资源上启用CORS,可以通…

程序的重定位

可以理解为编译和链接 过程中产生的地址项都是临时的相对的。编译的时候的地址,在链接时会被修改。最终链接后生成的bin文件的地址项,在加载运行时 也会被修改。 链接器会对所有的输入文件进行扫描,之后就可以确定段的大小,符号定…

从0开始搭建清华ChatGLM3 6b大模型(Windows RTX4090版)

目录 1、硬件及软件说明 2、安装Anaconda 3、安装Git版本控制 ​4、安装pytorch驱动 5、安装ChatGLM3 1、硬件及软件说明 硬件:主要是GPU卡内存要足够,本次搭建使用的RTX4090卡一张,单卡内存24G,为什么选择4090?…

如何在ArcGIS Pro中指定坐标系

在进行制图的时候,为了实现某些特定的效果,需要指定特定的坐标系,但是现有的数据可能不是所需要的坐标系,这时候就需要对现有的数据坐标系进行处理,这里为大家介绍一下ArcGIS Pro中指定坐标系的方法,希望能…

ECMAScript和JavaScript:深入理解它们的关系与区别

ECMAScript和JavaScript:深入理解它们的关系与区别 在讨论ECMAScript和JavaScript之间的关系及其区别时,我们首先需要澄清一些常见的误解。很多人会将这两个术语混为一谈,但实际上,它们指代的是不同的概念。今天,我们…

STM32存储左右互搏 SPI总线读写FRAM MB85RS2M

STM32存储左右互搏 SPI总线读写FRAM MB85RS2M 在中低容量存储领域,除了FLASH的使用,,还有铁电存储器FRAM的使用,相对于FLASH,FRAM写操作时不需要预擦除,所以执行写操作时可以达到更高的速度,其…

蓝牙物联网漏洞攻击的几种方式?

在物联网日益普及的今天,蓝牙技术的广泛应用为我们的生活带来了诸多便利。然而,正如一枚硬币有两面,蓝牙技术的普及也带来了新的安全挑战。近日,一项关于蓝牙物联网漏洞攻击的研究引起了广泛关注。这项研究揭示了蓝牙物联网所面临…

机器视觉在食品安全检测领域的应用与展望

​随着人们生活水平的提高,对食品安全的要求也越来越高。在这种背景下,机器视觉技术作为一种高效、准确的自动化检测手段,在食品安全检测领域扮演着越来越重要的角色。机器视觉系统通过模拟人眼的视觉功能,借助相机和计算机视觉算…

魅族手机怎么录屏?高清视频,轻松录制!

“有人知道魅族手机怎么录屏吗,新买的魅族手机,用了几天感觉挺流畅的,功能也很齐全,最近因为工作原因,需要用到录屏功能,但是我不知道怎么打开,就想问问大家,魅族手机怎么录屏呀。”…