Buod

Ang aklat na ito ay naglalaman ng mga karaniwang DAPAT at HINDI DAPAT GAWIN para sa Open Source na software.

Paunang Salita

Ang komunidad ng Open Source ay patuloy na lumalago. Sa bawat araw na dumarami ang bilang ng mga proyektong Open Source, gayundin ang hukbo ng mga nag-aambag para panatilihin sila. Bagaman nakakapanabik ito para sa industriya, maaari itong maging katakot-takot para sa isang bagong tagabuo sa komunidad. Ang aklat na ito ay naglalayon na magbigay ng iilang mga paaalalahanan para sa mga baguhan upang makatulong sa kanila na iwasan ang mga patibong sa pagbuo ng Open Source at para matuto mula sa pangkalahatang kaalaman ng komunidad.

Ika nga sa lumang kawikaan, "Ang oras at ang alon [at teknolohiya] ay hindi naghihintay sa sinumang tao". At sa abot ng aming makakaya, maging ang aklat ding ito. Tandaang tingnan ang bilang ng bersyon para sa mga update! Kami’y kasalukuyang nasa v0.1.17.

Lubos naming ikagagalak ang inyong tulong upang mapanatiling naka-update ang aklat na ito. Ang inyong mga komento, suhestiyon at pull requests ay malugod naming tinatanggap. Maaari niyong hanapin ang repository sa Github: https://github.com/eddiejaoude/book-open-source-tips.

Kung may iba pa kayong mga katanungan, mangyari lamang na makipag-ugnay sa may-akda na si Eddie Jaoude sa https://twitter.com/eddiejaoude.

Panimula

Nangingibabaw ang Open Source sa industriya ng software. Ang mga kampeon nito’y pinabibilangan ng mga tanyag na organisasyon tulad ng Facebook, Twitter, Netflix, LinkedIn at Google (Android/Chrome), ngunit ang mas mahalaga, ang hukbo ng mga dedikadong indibidwal na tagabuo sa buong mundo. Ang kanilang mga pagsisikap ay nagkaroon ng epekto sa halos bawat bahagi ng computer science, nagresulta sa milyun-milyong open source na proyekto na may bilyun-bilyong mga linya ng code!

Habang ang masaganang ecosystem na ito ay nagbigay ng malaking tulong sa buong industriya, maaari rin itong magpahirap sa mga baguhan na hindi alam kung saan magsisimula. Kung ikaw ay isang baguhan, maaari mong harapin ang mga katanungang "Paano ako makakaambag sa komunidad ng Open Source?" O, "Paano ako pipili sa pagitan ng napakaraming nakikipagkompetensiyang proyekto?". Ang mga sumusunod na mga DAPAT at HINDI DAPAT GAWIN ay naglalayon na masagot ang mga katanungang iyon, pati na rin ang ibang mga payo para sa nagbabalak na maging tagabuo ng Open Source.

Tara na’t sisirin natin ito.

PAALALA: Ang mga proyektong hindi isinapubliko sa simula ay may mas mataas na pagkakataong ipagkatiwala ang mga pribadong kredensyal sa kasaysayan, kung kaya’t mas nirerekomendang gawing pampubliko ang mga proyekto sa simula pa lang. Ang pagsasaad na sila ay hindi pa tapos ay hindi isang dahilan, dahil kailanman, sila ay hindi matatapos. Kung isinapubliko sa simula pa lamang, pinaparating lang noon na ang tamang pananaw ang ginamit kaya naman mababawasan ang panganib.

Mga Dapat Gawin

Readme file

Documentation is usually left to last. Start every project with at least a README.md with basic information, for example a description & quickstart guide, if you change features or functionality, try at least to update this with your commits.

Example README.md

# Name of Project

Include any project badges (e.g. CI) here at the top.

Description of project & its goals.

Also include what it does not do.


## Screenshots

Nothing says more than screenshots.


## Dependencies

Any dependencies required by the project.


## Installation

How to install on Mac...

How to install on Linux...

How to install on Windows...


## Usage

How to use the project


## Contribution SetUp

If people would like to contribute, what steps should they take.

Overview here and a link to the `CONTRIBUTION.md` file with more details


## Code of Conduct

Overview of Code of Conduct, with link to `CODE_OF_CONDUCT.MD`


## Change log / Release history

Major version & breaking changes


## Meta data

Any other useful information.

Bloke ng code

Gumamit ng pag-highlight ng syntax sa loob ng mga bloke ng code sa dokumentasyon para mapadali ang pagbasa nito.

GitHub syntax highlighting
Pag-highlight ng syntax sa GithubPag-highlight ng syntax sa Github

Talaksan ng Ambag

Isa sa mga pangunahing benepisyo ng isang proyektong Open Source at ng mga ambag nito sa komunidad. Pababain ang hadlang sa pagpasok gamit ang CONTRIBUTING.md na file sa ugat ng iyong proyektong Open Source. Magbasa pa tungkol sa Talaksan ng ambag sa GitHub

Kadalasan, ang mga proyektong open source ay naglalagay ng isang NAG-AAMBAG na file sa ugat na direktoryo. Ipinapaliwanag nito kung paano gawin ng isang kasapi ang mga bagay tulad ng pag-format ng code, pagsusuri sa mga inayos, at pagsusumite ng mga patse. Narito ang isang magandang halimbawa galing sa papet at isa mula sa factory_girl_rails. Mula sa pananaw ng tagapagpatuloy, maikli ngunit malinaw na pinapahayag ng dokumento kung paano pinakamabuting makipagtulungan. At para sa isang nag-aambag, isang mabilisang pagsusuri ng mga talaksang ito ay magpapatunay na ang mga isinumite nila ay sumusunod sa mga patnubay ng tagapagpatuloy.
— GitHub
Mga Patnubay sa Pag-ambag sa Github
Mga Patnubay sa Pag-ambag sa Github
Mga Patnubay sa Pag-ambag sa GithubMga Patnubay sa Pag-ambag sa Github

Magsaliksik ng mga proyektong Open Source

Alalahaning magsaliksik ng iba pang mga proyektong open source para makita kung paanong matagumpay na napapamahalaan ang ibang mga proyekto, at kung ano ang kinalalabasan nila.

Narito ang 10 halimbawa ng mga proyektong open source para makapagsimula ka:

Tip
 Kung mas marami kang mga proyektong open source na masasaliksik, mas makikita mo kung aling mga pagsasanay ang gumana at kung alin ang hindi. Mabibigyan ka nito ng mas maraming kaalaman sa kung paano mo gugustuhing patakbuhin ang iyong proyekto, base sa mga umiiral na proyektong iyong nakatagpo.

Alituntunin sa Pagkilos

Ang iyong komunidad ay kailangang makaranas ng pagiging ligtas, pagkakaiba, at pagkakabilang. Siguraduhin mong mayroon kang Alituntunin sa Pagkilos para sa iyong proyekto at komunidad. Magbasa pa tungkol sa Tipan ng Taga-ambag - Isang Alituntunin sa Pagkilos para sa mga proyektong Open Source

Ang Open Source ay lagi ng maituturing na pundasyon ng Internet, at sa pagdating ng mga panlipunang open source na network, ito ay mas naging tunay higit pa kaysa dati. Ngunit ang malaya, libre, at mga proyektong open source ay nagdurusa sa kakulangan sa pagkakaiba-iba - sa kapansin-pansin na mababang partisipasyon ng mga kababaihan, mga taong may kulay, at iba pang mga naka-marhinalisang populasyon.
— Tipan ng Taga-ambag
Maikling kabuuran ng problema
Isang madaling paraan para masimulang pagtuunan ng pansin ang problemang ito ay ang hayagang pagiging bukas natin, pagsalubong sa lahat ng mga nag-aambag, at ang pangakong pahalagahan sila bilang mga tao at pagpapaunlad sa kapaligiran ng kabutihan, kooperasyon, at pag-iintindi.
— Tipan ng Taga-ambag
Maikling kabuuran ng solusyon

GitHub template files

Issue & Pull Request templates really help keeping the project consistent & reminds people not to leave out certain useful information.

To add an Issue template to a repository create a file called ISSUE_TEMPLATE in the root directory. A file extension is optional, but Markdown files (.md) are supported. Markdown support makes it easy to add things like headings, links, @-mentions, and task lists to your templates.
— GitHub
GitHub Issue Template
Pull Request templates follows the same pattern: add a file called PULL_REQUEST_TEMPLATE to the root directory of your repository.
— GitHub
GitHub Pull Request Template
If you’re worried about the added clutter in the root directory of your project, we also added support for a .github/ folder. You can put CONTRIBUTING.md, ISSUE_TEMPLATE.md, and PULL_REQUEST_TEMPLATE.md files in .github/ and everything will work as expected.
— GitHub
GitHub Hidden Directory for Templates

Full details from GitHub for helping people contribute to your project

Licensing

It is not required to select a license, however by doing so, you are selecting "No License" which will default you to the T&Cs of GitHub. GitHub have created a great informational website to help you choose a license

Examples below from "Choose an open source license":

The MIT License is a permissive license that is short and to the point. It lets people do anything they want with your code as long as they provide attribution back to you and don’t hold you liable.
— Choose a License
MIT License
Note
 jQuery, .NET Core, and Rails use the MIT License.
The Apache License 2.0 is a permissive license similar to the MIT License, but also provides an express grant of patent rights from contributors to users.
— Choose a License
Apache License 2.0
Note
 Android, Apache, and Swift use the Apache License 2.0.
The GNU GPLv3 is a copyleft license that requires anyone who distributes your code or a derivative work to make the source available under the same terms, and also provides an express grant of patent rights from contributors to users.
— Choose a License
GNU GPLv3
Note
 Bash, GIMP, and Privacy Badger use the GNU GPLv3.
When you make a creative work (which includes code), the work is under exclusive copyright by default. Unless you include a license that specifies otherwise, nobody else can use, copy, distribute, or modify your work without being at risk of take-downs, shake-downs, or litigation. Once the work has other contributors (each a copyright holder), “nobody” starts including you.
— Choose a License
No License
Caution
 As a consumer, if you find software that doesn’t have a license, that generally means you have no permission from the creators of the software to use, modify, or share the software. Although a code host such as GitHub may allow you to view and fork the code, this does not imply that you are permitted to use, modify, or share the software for any purpose. Your options are: Ask the maintainers nicely to add a license, Don’t use the software, Negotiate a private license with a lawyer.

Git commit

Git commits should be small and atomic, be it a single change or small feature. This will make your commit messages easier to write and and changes will be grouped logically. There are many benefits to this:

  • Looking back through the history will be clear & easy to understand

    • if you want to find something

    • undo / remove some work

  • Automate the changelog generation as part of your build for tag & package etc

Commit message

  • Limit the subject line to 50 characters

  • Do not end the subject line with a period ..

  • If more than 50 characters use the body (description)

  • Wrap the body at 72 characters.

  • Use the body to explain why not how, this can been seen in the code

More information Git Commit

Tip
 Before doing the commit, check the git diff to make sure you are not committing anything you do not want to, or should not be.

Little and often

Steady projects are not only more stable, but are generally more successful & are better for your health. Trying doing a little every day or week.

Working frequently on your project gives your community confidence that you believe in your project & are in it for the long term not just that moment.

Plan ahead

Create tasks today ready in preparation for tomorrow. There are two benefits of this, allowing you tomorrow to immediately hit the ground running and to digest the tasks overnight as you might make some final tweaks.

Tip
 Plan a little ahead, not too much as things will change

GitHub Issue / Task

Keep these small. Tackling a large piece of work is always daunting and more difficult to find the time. The smaller the tasks, the more likely it is to be done and the lower risk it will be. But remember the task still needs to provide value to the project.

Include diagrams, screenshots, sub tasks & anything visual to help describe the issue & changes.

Tip
 Don’t forget you can use a sub task checklist on GitHub Issues Checklist. Sub task list are prepended with [ ] for incomplete & [x] for complete items.
Related

Laging Tumugon - Issue at Pull Request

Laging tumugon sa Issue at Pull Request sa napapanahong paraan, mas mainam kung ito’y sa loob ng 24 oras (kahit na ito’y sa pamamagitan ng komentong nagbibigay-alam ng pagtanggap o kahit man lang sa pagbasa ng isyu at ganap itong matutugunan sa 3 araw). Pinamamahalaan nito ang pag-asa sa kung kailan makakatanggap ng ganap na katugunan ang taga-ambag.

Pull Requests

If you spent the time doing the work, make sure you add a description to your your Pull Request to make it easier for the reviewer to digest your work. Raise an Issue first so a plan of action can be discussed before you begin the work and to remind yourself of the goals set out in that task.

Pull Requests should be linked to the original Issue it is trying to solve. This can be done with using # followed by the Issue No, e.g. #123. The Issue description will contain the information before, therefore the Pull Request description should contain the information after the changes. Include visual material too, for example diagrams & screenshots.

Remember, keep it small. For example if your changes contains a feature or bug fix & code styling changes, these should be in separate Pull Requests. Every project would rather have 10 Pull Requests, than 1 or 2 massive Pull Requests.

Tip
 Pull Request should be a single feature or change.

Multiple commits in a Pull Request highlight the creation steps of the Pull Request. Do not try to do everything in a single commit.

Comments do matter, if in doubt, put it in, they can more easily be removed than added. Don’t describe how, that is obviously in the code, describe why.

Review

Even if it is only you on the project, try to raise Pull Requests & get a friend to review it. This approach is invaluable as a second pair of eyes often picks up oversights.

Tip
 Even simple text changes might make sense to you but not to someone else. Review everything!

Pagsasa-awtomatiko - Mga Pagsusuri, Patuloy na Integrasyon (PI), Patuloy na Pagtatalaga (PP)

Isa-awtomatiko lahat! Ito’y tumutulong para mapababa ang hadlang sa pagpasok at pataasin ang pagkakaulit.

  • Ang mga pagsusuring isina-awtomatiko ay maraming taglay na kabutihan at nagbibigay kumpiyansa sa estado at kalidad ng aplikasyon:

    • Ang mga yunit na pagsusuri ay mabuti para sa disenyo at arkitektura ng pagpapaandar

    • Ang mga pagsusuri sa integrasyon ay mabuti para sa mga puntong mahahawakan

    • Ang mga punto por puntong pagsusuri ay mabuti para sa ganap na pagsusuri sa aplikasyon at pagkunuwa sa gumagamit

  • Ang pag-setup ng lokal na kapaligiran at pagpapairal sa lahat ng mga pagsusuring ito ay madali lamang

  • Pairalin ang mga isina-awtomatikong pagsusuri sa Patuloy na Integrasyon (PI) matapos maitulak ng isang tao ang mga pagbabago sa kowd sa isang tampok na sangay

  • Kung ang mga isina-awtomatikong pagsusuri ay matagumpay, italaga ang aplikasyon o mas kilala bilang Patuloy na Pagtatalaga (PP)

PAALALA: Ito ay sumasaklaw sa mga paglipat ng database schema, pagtatayo ng asset, at anuman na kinakailangan ng resultang produkto

Tip
 Ang TravisCI ay lubos na nirerekomenda sa mga proyektong Open Source. Napakadaling i-setup at gamitin, lahat mula sa simpleng `yamla file.

Prototyping - Get a prototype to your users quickly

Get feedback as soon as possible. Get a quick and dirty prototypes in front of some of your users will give you instant feedback and direction. Remember to make it clear it is a prototype.

Tip
 When building a prototype, the technology is less important to choose for longevity but for speed & possibly to test out potential technology solution.

Optimal time - work when at your best

People work better at different times of the day and night so find your most efficient and optimal time. Even if that is 11pm at night or 4am, try utilise your most productive time.

Not enough time

We all have the same 24 hours in a day available to us. It’s what you do with it that counts. Try to find a small amount of time per day, even 10 minutes when you are on the toilet - yes you heard me right "on the toilet". Multi tasking in that situation is possible, but trying to work while watching TV is very unproductive.

Mga pagpapabuti sa codebase - Iwan ang codebase ng mas mabuti kaysa ng natagpuan mo ito

Maraming mga imbakan ng code (kadalasan ang mga Closed Source) ang pumupunta galing sa masama patungo sa mas masama. Sa isang banda, ang mga proyektong Open Source ay posibleng magawi sa ganap na kabaligtaran nito dahil ito’y nakikita ng publiko. Kahit ang pinakamaliit na mga pagpapabuti ay nakakapagdagdag at talagang nakakatulong.

Tip
 Walang pagpapabuti na napakaliit. Gawin itong mas mabuti.

Fail fast with faster feedback loops

Feedback loops include:

  1. Locally

    • Linters

    • Automated tests

  2. Continuous Integration (CI)

    • Linters

    • Automated tests

    • Deployment with Continuous Delivery (CD)

  3. Manual / Exploratory testing

  4. …​

  5. All the way to the Client and then the User

The sooner feedback and/or change the more efficient it will be. Therefore on the flip side, the later the feedback and/or change the more costly it will be. Not only because it went through more steps to get there, but after the change has been made, it will have to go through all those steps again.

Tip
 Fail fast!

Kadalian sa Pagpasok

Gawing Mas Madaling Pasukin ang proyekto.

Ito ay may dalawang (2) sakop:

Ibaba ang hadlang sa pagpasok

Payagan ang lahat ng mga tao, mapa-baguhan man o higit na nakakaalam na maging parte ng komunidad at mag-ambag.

Ang resultang produkto ay dapat na magsilbi para sa lahat

Ang kakayahang makapasok ng lahat, kahit na may kapansanan (hal. may kapansanan sa paningin), ay kritikal sa tagumpay ng anumang proyekto.

Halimbawa:

  • Alternatibong alt teksto para sa mga imahe

  • Pag-input gamit ang keyboard at mouse

  • Mga salin para sa mga video

  • …​

Tip
 Maging mapagpabilang

GitHub Labels

These are really useful for various reasons:

  • Helps people filter their results, for example by defect, idea etc

  • If people want to contribute to your project a label that states help needed will stand out

  • Difficulty level. Contributors can filter by a level they are comfortable with. Having some sort of ranking system like beginner, intermediate and expert will help to make it easier for contributors, especially beginners to know which issues to tackle.

Tip
 Have different labels but don’t go label crazy, 10-20 is about right
Related

GitHub Milestones

Using Milestones not only gives you and your community visibility on the current goal and its progress, but also the future goals and what they contain.

Tip
 Align your Release versions with your Milestones
Related

GitHub Releases / Tags

When you are happy with the work done so far, make a Release so your community knows, this is a stable version. In the release notes, include change log.

Tip
 Align your Release versions with your Milestones
Related

Pagsasanga

Ang pagsasanga ay mahalaga kung nagtatrabaho sa isang grupo, at mas lalong mahalaga kung nagtatrabaho kasama ang mas malaking grupo na hindi mo pa nakikilala.

Protektahan ang iyong pangunahing sanga (karaniwang ang master o develop) at ang lahat ay dapat dumaan sa isang tampok na sangay at isang Pull Request. Ito ay dapat na pareho para sa lahat, mga publikong nag-aambag at mga inaprubahang tagapagpanatili.

Tip
 Mayroong maraming stratehiya sa pagsasanga, isang halimbawa ang Gitflow - maraming tao ang gumagamit ng bahagi ng Gitflow.
May kaugnayan

Mga Hindi Dapat Gawin

Big bang project

Don’t try to complete the project in a manic weekend, then ignore it for the next year. This is not good for your health nor does it look good for your project from the community’s view.

Tip
 Try to be consistent and do a little every week. Your thoughts and ideas will be better over time, this will prevent you from wasting time on redoing work when you get a light bulb moment a few days later.

God commit

God commits or big bang commits are not good because they are difficul to understand and review, these can block pull requests.

Also if a commit needs to be cherry picked in/out, then it makes it very difficult.

For example if files are being reformatted, this should be done in 1 commit, not with other changes otherwise it is confusing.

Tip
 Each commit should do one single item

God Pull Request

Similar to "god commit", god pull request are a bad idea. Reviewing god or big bang pull request are not only annoying & painful, but leave room for skim reviewing & therefore mistakes. A pull request should be a single feature.

Tip
 No one ever complained that a Pull Request was too small.

CV Driven Development

Most of us have heard of Test Driven Development (TDD). Do not fall in to the trap of CV Driven Development (CVDD). It is good to push your skills with new technology but do a little at a time to reduce the risk. Do not try every new technology you want to learn on the same project, this is very high risk, with the mostly likely outcome of little result & therefore frustration.

Tip
 Approximately 10 - 20% of new technology per project is a good, safe & exciting amount.

Weakest Dependency

Your project is only as good as your weakest dependency. Check the dependencies you include in your project before including them, look at their:

  • license

  • contribution activity

  • security

  • contributors

Tip
 Be aware of dependencies you include. It is great not to reinvent the wheel, there are usually a lot of choices available but make sure to do your research on the available libraries.

Apendiks

Acronyms

Table 1. Acronyms
Acronym Description Notes

TDD

Test Driven Development

GOOD! Wikipedia

BDD

Behaviour Driven Development

GOOD! Wikipedia

CVDD

CV Driven Development

BAD!

Resources

Tip
 Suggestions welcome…​read more at how to contribute
A great way to get involved in open source is to contribute to the existing projects you’re using. GitHub is home to more than 5 million open source projects. There are projects for every skill set like recipes, HTML/CSS, Ruby, Astrophysics and many more. This guide will cover what you might find in a typical project and how to make a great contribution.
— Contributing to Open Source on GitHub
https://guides.github.com/activities/contributing-to-open-source/
Open source works by having many people contribute to the creation and maintenance of software. Thing is, it works well only when people are actually contributing. Successful open source projects thrive on a wide variety of contributions from people with all levels of coding skills and commitment. If just one person fixes a compiler warning, closes a bug, or adds to the documentation, pretty soon you’re talking real progress. For many people, the hardest part is just getting started. So here are some suggested ways you can begin contributing right away, at whatever level is most comfortable for you.
— The Beginner’s Guide to Contributing to Open Source Projects
https://blog.newrelic.com/2014/05/05/open-source_gettingstarted/
GitHub is the home of many popular open source projects like Ruby on Rails, jQuery, Docker, Go and many others. The way people (usually) contribute to an open source project on GitHub is using pull requests. A pull request is basically a patch which includes more information and allows members to discuss it on the website.
— How to contribute to an open source project on GitHub
http://blog.davidecoppola.com/2016/11/howto-contribute-to-open-source-project-on-github/
It’s okay to not know everything, and take one step at a time to learn something new. Don’t waste a lot of time choosing the “right” project. If you know a project or a organization with a beginner-friendly community, just start there. A huge shout-out to all the open source maintainers who have been super responsive and encourage of new contributors. You are helping newcomers navigate huge code bases and contribute in maybe a small yet meaningful ways. Your efforts are truly appreciated and needed.
— A Beginner’s Very Bumpy Journey Through The World of Open Source
https://medium.freecodecamp.com/a-beginners-very-bumpy-journey-through-the-world-of-open-source-4d108d540b39#.an82epenf
You want to focus on the building blocks for your community before you get too deep in the code. "We’ll do it right later" doesn’t always work out well. If you don’t make governance decisions now, things can fall apart, or if you make the wrong decision, it could turn off potential community members going forward.
— How to care for the community over the code
https://opensource.com/article/16/12/community-over-code
For many web developers, accessibility is complex and somewhat difficult. The Accessibility Project understands that and we want to help to make web accessibility easier for front end developers to implement. Blind and visually impaired make up 285,000,000 people according to the World Health Organization (June 2012) with 39,000,000 categorized as legally blind and the remaining 246,000,000 visually impaired. Deaf and hearing impaired make up 275,000,000 (2004) in the moderate-to-profound hearing impairment category.
— Web Accessibility Checklist
http://a11yproject.com/checklist.html

English | Spanish | Filipino
PDF Download
v0.1.17