Geekly Articles each Day
📜 ⬆️ ⬇️

How to arrange an open source project

In my free and non-free time [1], I develop several of my projects on github, and also, as much as I can, participate in interesting projects for me as a programmer.


Recently, one of his colleagues asked for a consultation: how to put the library he developed on github. The library has nothing to do with the business logic of the company's application; in fact, it is an adapter to a certain API that implements a certain standard. By helping him, I realized that things that are intuitive and obvious to me for a long time, in this area, are completely unknown to the person doing it for the first time and far from Open Source.


I did a little research and found that most of the publications on this topic on habrahabr cover the topic of participation (contributing), or simply motivate in some way to join Open Source, but do not give exhaustive instructions on how to design your project. In general, in Runet, according to Yandex, the topic is covered by the motivation, etiquette of contribution and the basics of using github. But not in terms of the specific steps that should be taken.


So what is a stylish, fashionable, youth open source project in 201 * year?


This article does not solve the following tasks:



For those who know, and are the maintainer of their Open Source project, or the active contributor to others, most of the points discussed in this article may be familiar or intuitive. But, nothing stands still, and sometimes I notice new nuances for myself that I haven’t used yet and that would enhance the user experience. Therefore, in the comments I will be glad to see your interesting ideas that complement the article.


Must have


First I would like to consider the "must have" for any OS-project. The minimum gentleman's set, without which your project will not come across as complete. Personally, when choosing a library, I consider each of these items to be mandatory in order to add a new dependency in the package manager.


Github


Obviously, github is leading as the hosting of OS projects, and the flagship of modern development in general. The same obvious choice of hard currency for the project, which you decided to share with the world: git. No options. All alternatives are, de facto, underground, or harsh proprietary.


Each repository should have a .gitignore that matches the language and type of project. Choose a template for your case here .


The general rule: code - which is generated during development, testing, build / compilation, runtime - must be in gitignore.


License


The second small step for the project and a huge one for humanity is the selection and creation of a license file.


Github, when creating a project, allows you to select the appropriate license. The file should be called LICENSE , without extension.


Very detailed article on the topic of choosing a free license from marked-one


README.md


This file is the face of your project. It is seen by the user entering the main page. The contents of the same file will be shown in most services with which you integrate (for example, package manager registries, etc.).


At a minimum, it should contain a general description of the following points:


  1. The purpose of the library (project, tool, framework)
  2. System requirements (language version, resource requirements, system dependencies, required extensions)
  3. Steps to install, build, run
  4. Examples of use or references to documentation

Versioning (SemVer) and Change Log (CHANGELOG.md)


After the publication of the code, you are morally responsible to your users for its performance in the event of updates. For this smart people have been invented two great things. I will cite only references, it is not difficult to understand them, you just need to read:



Always follow them, and your karma will be immaculate.


Testing


If you are not infected with TDD, then I can infect =)


How can you prove that the code works at all, if not with tests? How to prove that 100% of your code works as expected, as not full coverage?


Of course, 100% coverage does not give a 100% guarantee of the absence of bugs and loyalty to the implementation, but like nothing else brings this unattainable ideal closer.


Tests are the only formal way to prove the correctness and performance of the code to a potential programmer user. Promise to leave the humanities, colleagues from QA and girls.


CI


Travis-ci connects to github in a couple of clicks. The presence of .travis.yml in the repository is necessary, unless, of course, you are using something more complex.


Batch manager


If there is a package manager for your platform, work hard so that your code can be obtained through it. Composer, npm, maven, etc.


It is also important that the current version (in accordance with SemVer, aha) automatically, after passing the CI (and testing, aha), got into the registry.


Fortunately, for most mainstream languages, such managers exist and are integrated with github / travis in a couple of clicks / lines of the config.


Dependencies of your code, of course, must be properly executed using the configuration file of the same manager.


Dependency Injection, SOLID, etc


Try also to look at your code from the side.


If this is a general purpose library or framework: how convenient would it be to use it in a project built on a completely different framework or without it? What about Open / Closed? Is it possible to inject through the interface one of the components of your library that someone needed to change? Are all options easy to configure?


If this is a utility, for example the command line: is it well suited for embedding into existing automation scripts? What about helpful error messages and correct return codes?


The most viable and successful projects are those that were born in agony, in real combat conditions and extracted from the depths of the mine-paste into the white light.


Without trying on the role of a user, you can not adequately design the application interface.


Standards


Use the standards of the language and its community: JSR, PSR, generally accepted code styles. If you did not delve into this jungle before, it's about time!


Look at the mainstream libraries for similar tasks in your language: which interfaces and standards do they implement?


This is not only about specific RFCs, but in general it concerns standard approaches to solving typical problems.


Not critical, but very desirable


Detailed documentation, examples, FAQ


Minimal examples of using your code should be in the readme. But, I hope, as a programmer, you will agree how pleasant it is to quickly find answers to your questions.


There are several ways to organize proactive help to your users. Each of them is convenient and effective, depending on the specifics of the project and the audience.


  1. Wiki documentation. It can be placed on the same github, either as a set of md files in the repository itself or on github pages, or in general on a separate site.
  2. Small repository projects with typical usage examples. It can be very useful for projects that represent something between a framework and a library.
  3. FAQ - updated from your own and user experience.

For reactive support, github has issues.


Files CONTRIBUTING.md, CONTRIBUTORS.md, ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md


If you are lucky and you are not the only developer, or so ambitious that you are counting on a wild surge of fresh energy immediately after publishing on github, then this kit will help you.


In the first case: to work according to the same rules and not to holivarit over trifles.


In the second: to facilitate the participation of newcomers and eliminate misunderstanding.


This also includes the use of linkers, static analyzers, autoformatters and other things - all this greatly facilitates team development.


In the github setting, you can find a checklist that will orient you to what the project lacks for a complete gloss. Checklist example: https://github.com/github/gitignore/community (any repository has a similar page, even yours))


Chic, shine, beauty


And finally, optional chips, which, nevertheless, make a pleasant impression and can greatly help the users of your code.


Badges


Great stuff. It is very convenient at a glance at the README to get an idea of ​​the status of the project. Personally, I consider the following characteristics to be the most obvious:



The main thing is not to overdo it.


Integration with services


The CI market has been developing very actively in recent years and there is a huge choice of services for code analysis, storage of assembly artifacts and testing, etc. Most of them, as a rule, are easily integrated with github and are free for open source projects.



Share interesting comments in the comments!


Docker?


It would seem, what have the docker?


But: it can be used for testing, developing and supplying your offspring.


Some CI services use docker. Some types of testing are conveniently automated using containerization.


Previously, you had to use vagrant to unify the working environment. Docker may well take on this task. Many assembly tasks that need to be performed on a developer's machine can be containerized. This will help to avoid additional efforts to configure the local machine for the project and problems like "and everything works for me ...".


Some software solutions are conveniently delivered as a docker image, given that many already use docker-compose and stack in their projects. In this case, the connection of your development is simplified to a couple of lines in docker-compose.yml.


[1]: I believe that in the framework of the work almost always there is a place Open Source. For example: in the previous work, I used one of my own libraries in production, and left another service, developed on weekends for the current needs of the project, also in agreement with techirm, on github and docker hub. If the library is not connected with the business logic of the project, and you are ready to give it a couple of hours at your leisure, then an adequate bosses will always meet you. After all, this is a mutually beneficial step: the company receives bonus man-hours (now, and potentially even after you leave), you are a public portfolio beyond the scope of the NDA.


')

Source: https://habr.com/ru/post/341166/

More articles:


All Articles