Tag Archives: open source

News, Tech Culture, , , ,

Early in september Netflix invited a handful of Spinnaker’s core contributors and companies to its engineering headquarters in Los Gatos California to discuss all things Spinnaker. Here’s a recap of some key takeaways:

Extending Spinnaker
David Stenglein, Kenzan’s SVP of architecture and engineering, moderated a panel focused on extending Spinnaker. Panelists featured speakers from Google, Armory, Netflix, Oracle and Cerner. The panelists gave advice on how to best extend and modify Spinnaker by doing things such as adding your package to the classpath of Spinnaker. If you want to extend Spinnaker to better support your company and infrastructure this discussion is a good place to start.

Canary Deployments
One of the most widely anticipated features of Spinnaker is first class support for canary deployments. Google and Netflix have teamed up to work on a new microservice called “kayenta”. While Spinnaker can already do the first half of a canary deployment it’s still lacking a proper judge. Kayenta plans to fix this by monitoring metrics such as disk utilization, CPU, and error rates and compare them to a baseline deployment to determine if any given deployment is healthy enough to get full production traffic or if it should be automatically rolled back and the developers notified.

Community
At the end of the conference Netflix, Google, Kenzan and several other companies sat down to discuss the future of Spinnaker and its roadmap going forward. A few things stood out:

  • Many of us had faced the same problems and came up with identical solutions, often using the same programing language.
  • We realized just how big of an impact open sourcing even our smallest tools could have.
  • We also talked about the limitations of using Slack, Github, or Stackoverflow when used for long term planning, discussion, and sharing. We came to the consensus that we need some sort of message board system so that we can share our pipelines, projects, and ideas in a single and easily searchable place.

We all play a vital role in Spinnaker’s future and we very much look forward to more actively engaging with the entire community.

You can see all the main presentations and breakout sessions here:

 

Tech Skills,

Since it was created in 2007, GitHub has not only become the primary destination for open source development and distribution, but also one of the largest collaborative platforms on the internet. GitHub’s open source practices have established the platform as one to the most important tools for developers and gives coders of all levels a place to learn new skills, contribute to a vast number of projects and work alongside other programmers. Kenzan is a company that leverages the benefits of open source software by opening many of our  projects to the community and contributing to others in order to support the technology landscape at large.

More than just a GUI on top of Git, the GitHub platform  offers many powerful tools  and features that can help maintainers of OSS projects provide a more useful, transparent, and open experience for their project and their community. In this post, we will walk through some of the best practices that can help make an OSS project successful and inspire community participation and contribution.

Getting Organized

In order to ensure a consistent path to PR integrity, acceptance and delivery, it is important to make sure team permissions are setup appropriately.  At Kenzan, we identify maintainer and contributor teams for our projects.  The primary goal is to establish a protected branch (typically master) for a given repo and those who should have write access to it. Protected branches allow you to give read access to everyone else in the organization or an internal contributing team, but only permit a small team to actually be able to manage the main line of development. Roles can be defined as:

  • Maintainers – Act as the stewards of the project with sole access to protected branches like master
  • Contributors – Community team within the organization that are allowed to read and push branches within the repo

Below is an example of a sample configuration that protects the master branch with options like:

  1. Ensuring only the maintaining team can push to master
  2. Requiring PR approvers
  3. Requiring PRs pass a Continuous Integration build

Pro-Tip!
Always use teams for delegating repo access, for both maintainers and contributors. This will ensure easy addition and removal of members, as well as a simple and streamlined permissions strategy for your organization and repositories.

Welcoming Contributions

Great software is developed by many people contributing more than just code like testing, refactoring, documentation, and more.  However, each project is generally run in a particular way, and so clearly communicating these specific processes and workflows can help make a big difference in the growth and success of your project.  Guiding developers and contributors through the following recommendation will  help ensure understanding and onboarding from the start.

  • README.md – First impressions are everything, so a README that includes important information like an overview (your “elevator pitch”), installation/setup, usage and example, license, etc., will ensure first timers to your project know exactly what it is, what it does, and if it is right for them.
  • CONTRIBUTING.md – by including a CONTRIBUTING.md in your project’s root, you can define the Contributing Guidelines for your project. With this, GitHub can prompt all users who open an issue or PR to your project with a link to read it.
  • LICENSE – Having a LICENSE file is important to disclose to users how your project can be consumed, used, and distributed. In addition, be aware of the license expectations of any dependencies your project has.
  • Webhooks – Webhooks allow “push notification” integration with 3rd party services such as a Continuous Integration server like Jenkins.  Anything that can be automated in your project (linting, static analysis, style guide, tests, etc) should be scripted and run against every PR to provide fast turnaround and feedback to contributors (i.e. pass or fail).  Kenzan uses GitHub PR Builder.
  • Issues / PRs – GitHub has done a lot to improve the features around these workflows, in particular Pull Request Templates, fields for reviewers, assignees and labels, reactions and many others.  These are great features for identifying/establishing ownership and status.

Below is an example of a PR making use of some of the available PR fields like

  1. Contributing guidelines (the yellow banner)
  2. PR templates (the content inside the textarea)
  3. Reviewers / Assignees

Pro-Tip!
Always create an issue for any non-trivial change. This promotes discussion of the feature to happen independently of the code review itself.

Bonus!
If you link to the issue in the PR, using #XX (where XX is the issue number) GitHub will close the issue when the PR is merged.

Steering the Project

As a project grows and matures, planning out goals and improving documentation will naturally require some additional organization.  No worries, GitHub has you covered!

  • Project Management – Leverage features like milestones and projects to group issues into related buckets of work.  At Kenzan, we see projects as sprints (in agile terms with one or more projects making up a milestone. This allows a project’s mantainer to communicate their roadmap clearly and can help direct contributors to where help is most immediately needed.  It also helps establish feature / bug delivery expectations.
  • Release Management – Whenever a Git tag is pushed to your repository, GitHub will create a link to a page for that tag, thus enabling  the easy creation of release notes for every tag.  This is useful for tracking progress over time and to keep a record of features and bugs completed.
  • Wiki – The wiki is a great place to organize and manage supplemental information for consumers and developers. Rather than pack everything into the README, the wiki can be used to establish separate documentation for onboarding, migration guides, API docs and more.
  • GitHub Pages – GitHub Pages are a simple way to generate web content from source code or even just markdown and deploy that to a domain. This is a simple way to create a nice product, marketing, or API documentation for users with minimal fuss and overhead.
  • Gitter – Gitter is a chat platform that integrates with popular development/OSS tools like GitHub, Jenkins, Bitbucket, Trello, and others that can allow you to foster a real time community around your project, assist others or let the community jump in and help!


In the below screenshot, we can see an example of the project feature in action, tracking issues sourced from the issue tracker.

Closing Thoughts

Hopefully this has helped shine a light on some of the great features and workflows GitHub  offers to support the development of your own OSS project.  It is important to remember that Open Source is an inclusive process by nature, so make sure to be open to feedback and respectful of all contributions. OSS will undoubtedly attract contributors of all skills levels, so make sure to engage openly and without prejudice. Likewise, if there are small bugs or documentation tasks, you can recommend those to newcomers as part of your onboarding documentation. With robust documentation around your project and workflows, developers are more likely to contribute and newcomers can self-onboard, with minimal guidance from you.

Most importantly, developing software should be fun and rewarding.  When the right people get together with the right tools and in the right way, great things can happen. Happy coding!