Open Source Developer Guide and Best Practices at FOSSASIA

I would request you to please guide me as to how can I collaborate with you and also how can I contribute effectively to the organization.

At times I might get up to 20 private mails per day about “How to contribute to Open Source”. Usually I will direct developers to our mailing list or chat channels if they are asking about a specific project. But, how do contributions work at FOSSASIA? How can new developers join projects effectively? We have tried many different ways and spent a lot of time communicating with newcomers, many of them new to Git and Open Source development.

Over the years we have gotten better at helping new developers, designers and other contributors to join up. We have more than 1300 registered developers in our GitHub organization today. Not all of them can contribute every day, but we do have thousands of commits every year.

So, how are we able to scale up? I believe one reason are our Best Practices. We didn’t have a document “FOSSASIA Best Practices” yet, but in our daily work we have established excellent (mostly unwritten) best practices, that I would like to share in a concise form here now as a reference for new developers.

Happy to get your feedback and comments.

Development Best Practices at FOSSASIA

Culture and Communication

  • Please adapt your language to non-native English speakers and be super friendly. Remember we are an international community with contributors mainly from Asia and Europe. We are not used to swearing and will mostly understand words literally. At all times ensure your tone stays appropriate and friendly in the FOSSASIA community.
  • Stay modest. Sometimes newcomers already have an amazing knowledge in some areas. Still remember, it is no reason to be arrogant. Even the best developer does not know everything.
  • Be nice and welcoming. Why not add “please” in an issue or a comment “Thank you” in a pull request if someone did a good job? Show your appreciation for the good work of your co-developers.
  • If you are involved in a topic you don’t understand yet, try to learn yourself as much as possible from public channels (wikipedia, stackoverflow) but also do not hesitate to ask questions to other developers.

Communication Channels

Every project at FOSSASIA has its own channels. Many projects use Gitter, some Slack or IRC. Usually you will find information of the main communication channels of a project in the Readme.md.

While we are a community of Open Source and Free Software developers we still reserve our right to use whatever tools we deem necessary to help us to achieve our goal of developing the best possible Open Technologies – software and hardware. It is one step at a time 🙂

Private and Public Chat or Issue Tracker

Chat is a great way to connect with other contributors, but not all contributors are there all the time (consider time difference and personal schedules) and they are not always available to chat. Chat tends to be unstructured and with lots of people in a room there are often a number of threads. Therefore chat is great for help on setup issues and things where you got stuck.

Do not use chat for feature requests and detailed discussions on issues. These things are best for the issue tracker, where people from different timezones can join and where a focused conversation on one specific topic can happen.

Some people try to overcome the unstructured chats by switching to private communication. This shuts out other contributors who might have similar issues. A result I often observed is also, that contributors will bring up arguments in discussions like “I have discussed this already with xyz privately and he agrees”. Other contributors have not seen this discussion if it has not been taken place in public and we haven’t seen the arguments. We don’t know if xyz really agrees or if it was misunderstood. Private conversations are not transparent. Surely, there are cases where private chat is needed, e.g. for specific deployment questions of projects, but whenever you talk about development, please switch to public chat or open an issue.

Feature Requests and Bug Reports

  • Some newcomers are not accustomed to issue trackers and might try to inform developers on the mailing list, chat or even write private emails about bugs and features, but the right place to do this is: The issue tracker of a project.
  • Any bug or feature, please open an issue in the issue tracker right away and indicate if you want to work on it yourself.
  • Please include all relevant information when you submit an issue and wherever possible a link, information about the code that has issues and a screenshot.
  • When you file a bug report on the issue tracker, make sure you add steps to reproduce it. Especially if that bug is some weird/rare one.

Join Development

  • Before you join development, please set up the project on your local machine, run it and go through the application completely. Press on any button you can find and see where it leads to. Explore. (Don’t worry. Nothing will happen to the app or to you due to the exploring. Only thing that will happen is, you’ll be more familiar with what is where and might even get some cool ideas on how to improve various aspects of the app.).
  • If you would like to work on an issue, drop in a comment at the issue. If it is already assigned to someone, but there is no sign of any work being done, please free to drop in a comment so that the issue can be assigned to you if the previous assignee has dropped it entirely.

Commits/Pull Requests

  • All pull requests need to be associated to an issue.
  • All PRs need to be assigned to the person working on it.
  • If an issue cannot be completed in less than a day, it should be broken up into multiple issues.
  • Make pull requests from your own forks (even if you have write rights to the repository, do not create new branches, develop on your own branches).
  • State the actual change or enhancement in the commit message of PRs (do not just state “Fixes issue #123”).
  • Add the issue number into the description (this helps to speed up reviews as reviewers can simply click to get more info in the issue itself).
  • Write clear meaningful git commit messages (Do read http://chris.beams.io/posts/git-commit/).
  • Match pull requests with issues and make sure your pull requests description contains GitHub’s special keyword references that automatically close the related issue when the pull request is merged. (More info at https://github.com/blog/1506-closing-issues-via-pull-requests).
  • When you make very minor changes to a pull request of yours (like for example fixing a failing travis build or some small style corrections or minor changes requested by reviewers) make sure you squash your commits afterwards so that you don’t have an absurd number of commits for a very small fix (Learn how to squash at https://davidwalsh.name/squash-commits-git).
  • Add a screenshot if you changed anything in the UI of a project. When you’re submitting a pull request for a UI-related issue, please add a screenshot of your change or a link to a deployment where it can be tested out along with your pull request. It makes it much easier for the reviewers and helps to speed up the process. You’ll also get reviews quicker.
  • Add a link to your deployment of the project, where reviewers can check out what you have changed (especially for smaller changes this is very helpful as the reviewer might not even need to set up the system itself and test it. Again this speeds up the review process a lot).
  • Always ensure CI and tests are successful.
  • Help to resolve merge conflicts (especially if there are several PRs at the same time, merge conflicts are common. Help the reviewers and solve merge conflicts to speed up the process.).
  • Merging Pull Requests should only happen if at least two contributors reviewed the PR and approved it.

Scope of Issues and Commits

  • Stay focused on the issue and its specifics: Sometimes it is tempting to do more changes in a pull request and simply add a nice little feature after mentioning it in the issue tracker. Please do not do this. Contributors will look at the title of issues usually to check if it is relevant for them. For example, if an issue is about changing a font, do not also change the color even if this seems like small change to you. Many projects have a design template and standard colors etc. that they want to achieve. So your changes might need to be discussed in a bigger setting even if they seem small to you. Same applies to many other areas.
  • Do only the changes in a pull request that are mentioned in the issue. Do not change anything else without ever mentioning it (remember match issues with pull requests).

Branch Policies

Most FOSSASIA Projects have:

  • a development branch (which is the working branch. Please commit to this branch.) and
  • a master branch (which is the stable branch).

Some projects also keep additional branches e.g.:

  • gh-pages for documentation purposes (often autogenerated from md-files in docs folder)
  • apk branches for Android apps (often autogenerated with travis).

Getting Started

  • Newcomers are sometimes afraid to make a pull request. Don’t be! It is the responsibility of reviewers to review them. And Git is a beautiful tool when it comes to reverting pull requests with errors.
  • In simple issues keep it simple and “simply” contribute, e.g. in an issue “change the color of the button from green to red”, there is no need to mention and ask “here is a screenshot where I changed the color to red. Should I make a PR now?”. Just make the pull request and wait for the feedback of the reviewer.
  • Take on responsibility early and help to review other contributions. Even though you do not have write access in a repository you can already help to review other commits.

Documentation

  • Please ensure you provide information about your code and the functioning of your app as part of every code contribution.
  • Add information on technologies and the code into the code itself and into documentation files e.g. into the Readme.md or /docs folder. Documentation is not a thing that should be done at the end after a few weeks or months of coding! Documentation is a continuous effort at every step of software development.
  • If you add new libraries or technologies add information about them into the Readme file.
  • If you implement a different design or change the css in a web project, please add information to the design specifications/template. If there are not any design specifications in the project yet, why not start them and add a section into the Readme.md to start with?
  • Always help to keep documentation up to date and make it easy for new contributors to join the project.

 

Thank you for helping to define many of the practices while working on the Open Event project to the developer team and for additional input and links to Niranjan Rajendran.

Links to Other Resources

Continue ReadingOpen Source Developer Guide and Best Practices at FOSSASIA

How to join the FOSSASIA Community

We often get the question, how can I join the community. There is no official membership form to fill out in order to participate in the Open Tech Community. You simply start to contribute to our projects on GitHub and you are already a member. So, let’s work together to develop to develop social software for everyone!

The FOSSASIA team welcomes contributors and supporters to Free and Open Source Software. Become a developer, a documentation writer, packaging maintainer, tester, user supporter, blogger or organize events and meetups about our projects.

Women in IT discussion in the community

Here are some ideas how we can collaborate

Download our Open Source applications, install them and use them

The first step of joining a project is always to download the software and try it out. The best motivation to support a project is, if the project is useful for yourself. Check out our many projects on github.com/fossasia and our project social media Open Source search engine on github.com/loklak.

Show your support and ★star FOSSASIA projects

Help to motivate existing contributors and show your support of FOSSASIA projects on GitHub. Star projects and fork them. Doing something that people like and that helps people is a great motivation for many.

Learn about best practices

We have formulated best practices for contributing to Open Source to help new contributors to get started. Please read them carefully. Understanding our best practices will help you to collaborate with the community and ensure your code gets merged more quickly.

Subscribe to news

Subscribe to the FOSSASIA Newsletter to stay up to date on new software releases, events and coding programs here on the main page.

Read the blogs and support users on the mailing list

Learn from Open Tech articles on our blog that are written by developers, contributors, volunteers, and staff of companies supporting the FOSSASIA network. Sign up for the FOSSASIA Mailing List and keep reading our blog at blog.fossasia.org.

Follow us on Social Media

Show us you interest in FOSSASIA’s Open Technology and keep up to date on new developments by following us on Twitter and retweeting important updates: twitter.com/fossasia

And, become a member on social networks like Google+ and Facebook and connect with other contributors:
* Facebook www.facebook.com/fossasia/
* Google+ plus.google.com/108920596016838318216

Join and support the FOSSASIA network at community events

Set up a booth or a table about FOSSASIA at Open Source community events! There are many events of the open source community all over the world. The core team of FOSSASIA is simply not able to attend all events. You can support the cause by making the project visible. Register as a member of the FOSSASIA community at events, set up an info point and showcase Free and Open Source projects. Check out for example FOSSASIA event calendar calendar.fossasia.org or our meetup group in Singapore: meetup.com/FOSSASIA-Singapore-Open-Technology-Meetup

Translate our projects and their documentation

Do you speak more than one language? Most Open Tech projects are 100% volunteer translated, which means you can be part of a translation team translating software and documentation thousands of people will use. Start now and check out our GitHub repository.

Mini Debconf Participants in Saigon

Continue ReadingHow to join the FOSSASIA Community

How to get contributors from Asia for your Open Source project – Talk at Libre Graphics Meeting Brussels

I had the chance to talk about the topic of how to get contributors for Free/Libre/Open Source projects from Vietnam and Asia at the Libre Graphics Meeting Brussels. It was a a fantastic experience to meet developers and contributors from all over the world and I hope to support projects with the insights of this talk.

The situation in 2010 in Asia is, that many people still do not know about Free and Open Source. We need more people to support each other and help new users und developers. We need more developers in Vietnam to adapt existing solutions for Vietnamese and Asian users. We need people to organize events, where we can meet face to face. We need mentors, who developers and contributors can turn to. We need business people who understand business models and opportunities around Free and Open Source. We need you! FOSS can be a sustainable model for Vietnam as it is for other countries. Please join us in our effort for education, spreading knowledge, developement of better, faster and energy-saving software, designing easy to use interfaces and promoting opportunities for everyone with Free and Open Source.

Links

* Libre Graphics Meeting 2010: http://libregraphicsmeeting.org/2010

* LGM: http://libregraphicsmeeting.org

 

Continue ReadingHow to get contributors from Asia for your Open Source project – Talk at Libre Graphics Meeting Brussels