How to make an Open Source project
In the free and leisure time[1] I develop some of my projects on github as well, as the forces involved in life interesting for me, as a programmer, projects.
Recently one of my colleagues asked for advice: how to upload a library on github. The library has nothing to do with the business logic of the application, the company in fact it is the adapter to some sort of API that implements a standard. Helping him, I realized that things intuitive and has long been obvious to me in this area, completely unknown to the person to do it for the first time and far from Open Source.
I did some research and found that most publications on this topic on habrahabr cover the topic of participation (contributing), or simply motivate some way to join Open Source, but do not provide exhaustive instructions on how to properly execute your project. In General, in Runet according to Yandex, the subject is illuminated from the side of motivation, etiquette indemnity and use github. But not from the point of view of specific steps that should be taken.
So what is stylish, trendy, youth Open Source project in 201* year?
This article does not solve the following tasks:
the
-
the
- motivation to participate in Open Source the
- PR and promotion for their OS projects the
- discussion of the details of programming the
- basic usage of git / github
For those who know, and is maintained by its Open Source project, or active contributors to the strangers, most discussed in this article, points can be familiar or intuitive. But nothing stands still, and sometimes I notice new nuances that were not yet used, and which would have increased the convenience of the users. So the comments I will be glad to see your interesting ideas to complement article.
Must Have
First, I would like to consider a "must have" for any OS project. The minimum set of gentlemen, without which your project will not be to impress finished. I personally, when choosing a library, I think each of these items is mandatory in order to add a new dependency in the package Manager.
Github
it is Obvious that github is the leader of the hosting OS projects, and the flagship of modern development generally. Also the obvious choice of SCR for the project that you decided to share with the world: git. No options. All the alternatives are, de facto, an underground, or severe proprietaria.
In each repository must be .gitignore matching the language and type of project. Choose a template for your case here.
General rule: code which is generated in the process of development, testing, build/compile, runtime, should be in gitignore.
License
the Second small step for the project and vast for humanity — the choice and the creation of the license file.
Github, when you create a project, allows you to choose a suitable license. The file must be named LICENSE, without expansion.
A detailed article on the subject of choosing a free license from marked one
README.md
This file is the face of your project. It sees the user going to the main page. The contents of this file will be shown in most of the services with which you integrate (e.g. registries of package managers, etc.).
at least it needs to contain a General description on the following items:
- System requirements (the version of the language, resource requirements, system dependencies, required extension) the
- Steps for installation, Assembly, start-up the
- Examples of usage or documentation links
the purpose of the library (project, tool, framework) the
Versioning (SemVer) and change log (CHANGELOG.md)
the
Always follow them, and your karma will be immaculate.
Testing
If you are not infected with TDD, you can infect =)
how can we prove that the code actually works if you don't test? How to prove that 100% of your code works as expected, not as full coverage?
of Course 100% coverage is not 100% guarantee the absence of bugs and fidelity of implementation, but nothing else closer to that unattainable ideal.
Tests is the only formal method to prove the correctness and the efficiency of the code to the prospective user who is a programmer. Promises Express the Humanities and colleagues from QA and the girls.
CI
Travis-ci connects to github in a few clicks. The presence of .travis.yml in the repository — I will, of course, if you don't use something more complex.
Batch Manager
If your platform has a package Manager, you might want to have your code could be received through him. Composer, npm, maven, etc.
it is Also important to current version (according to SemVer, yeah) automatically after passing the CI (and testing!), come in the list.
fortunately, for most mainstream languages these managers have and integrate with github / travis in a few clicks / lines of config.
based on your code itself should be properly executed with the configuration file the same Manager.
dependency injection, SOLID, etc
Try to look at your code.
If it's a General purpose library or framework: how comfortable is it to use project built on a completely different framework, or without it? How about Open/Closed? Is it possible to Sangachal interface one of the components of your library that someone needed to change? All options lend themselves to easy software configuration?
If a utility, for example the command line: if it is suitable for integration into existing automation scripts? How about useful error messages and return codes, correct?
the Most viable and successful projects are those that were born in pain, in real combat conditions and extracted a copy-paste on white light.
Not having donned the role of a user, you will not be able to adequately design the application interface.
Standards
Use the standards of the language and its community: JSR, PSR, common code styles. If you have not delved into the jungle, it's time!
Look at mainstream libraries for similar problems in your language: which interfaces and standards implement them?
It's not only about the specific RFC, but in General it applies the standard approaches to solving common problems.
Not critical, but it is very desirable
Detailed documentation, examples, FAQ
Minimal examples of usage of your code should be in the README. But I hope that you, as a programmer, you will agree how nice it is to quickly find answers to their questions.
There are several ways to organize proactive assistance to your users. Each of them in their convenient and efficient, depending on the specifics of the project and the audience.
-
the
- Wiki-documentation. Can be placed on the same github, or as a set of md files in the repository or on github pages, or even on a separate website. the
- Small projects repository with typical examples of usage. It is very useful for projects that represent something between a framework and a library. the
- FAQ — updated from their own and user experience.
For reactive support github has issues.
Files CONTRIBUTING.md CONTRIBUTORS.md ISSUE_TEMPLATE.md PULL_REQUEST_TEMPLATE.md
In the first case: work by the same rules and not bolivarite for nothing.
second: to facilitate the participation of newcomers and to eliminate the misunderstanding.
this also should include the use of linters, static analyzers, autoformatter and other — all this greatly facilitates team development.
To configure github you can find a checklist that will guide you what's missing from the project for a full gloss. An example of the checklist: https://github.com/github/gitignore/community (the same page have with any repository, even your))
Chic, brilliance, beauty
And finally, optional chips, which, however, make a good impression and can considerably help users of your code.
Badges
a Great thing. Very comfortable from the first glance at the README to get an idea about the status of the project. Personally, I think the most visible of the following:
the
-
the
- interest coverage the
- latest stable version the
- downloads statistics in the registry / stars, parametria, or other evidences of popularity or relevance
the Main thing is not to overdo it.
Integration services
the CI Market last years very actively developed and there is a huge range of services on code analysis, storage artefatos build and test, etc. Most of them usually are easily integrated with github and is free for open source projects.
the
-
the
- https://codecov.io the
- https://codeclimate.com/ the
- https://www.bithound.io the
- https://scrutinizer-ci.com/ the
- https://codeship.com/ the
- ... thousands of them under any language and task
Share in the comment interesting finds!
Docker?
it would Seem, what's Docker?
But: it can be used for testing, development, and delivery of your offspring.
Some CI-services using Docker. Some types of testing it is handy to automate by means of containerization.
Previously you had to use vagrant for the unification of the working environment. Docker may take this task on yourself. Many of the tasks for the Assembly, which should be done on the developer's machine can be containerservice. This will help to avoid additional effort for setting up the local machine to a project, and problem type "and everything works".
Some of the software solutions it is convenient to put in a Docker image, given that many are already using docker-compose and stack in your projects. In this case, the connection of your design, simplified to a few lines in docker-compose.yml.
[1]: I think that part of the work almost always there is a place Open Source. For example: in previous work, I used one native library in production, and other services developed on the output to the current needs of the project, also in agreement with ahderom, left on github and docker hub. If the library is not connected with business logic project and you are ready to give it a few hours at leisure, then the appropriate authority will always come towards you. Because it is mutually beneficial: the company receives certain amount of hours (now, and potentially even after you left), you — public portfolio outside of the NDA.
Комментарии
Отправить комментарий