Development @ Sourcefabric Release 0.1
Holman Romero
February 28, 2014
Contents
1 Contributor’s Guide 3 1.1 Reporting issues...... 3 1.2 Requesting features...... 4 1.3 Writing code...... 4 1.4 Documenting...... 6 1.5 Localizing...... 7 1.6 Helping others...... 7
2 Developer’s Guide 9 2.1 Git repositories...... 9 2.2 Testing...... 11
3 Overview 13 3.1 Release process...... 13 3.2 Security policy...... 14
4 Community 15 4.1 Community...... 15
i ii Development @ Sourcefabric, Release 0.1
At Sourcefabric we develop open-source software for media organizations. There are several reasons why we develop Open Source software, one of our favourites is the chance to work with users. You can also be part of that community, helping us and helping others.
Contents 1 Development @ Sourcefabric, Release 0.1
2 Contents CHAPTER 1
Contributor’s Guide
Whether you are a journalist, a student or an experienced programmer, anyone has the power to contribute and support us to develop better software, you can start doing it in different ways, and here you will learn how.
1.1 Reporting issues
Found a security hole? If you think you have found a vulnerability issue, please report it only by sending an e-mail to secu- [email protected]. The security team will process the request before revealing any public announcement. For further information on this please read our Security policy page.
We love getting bug reports, and we mean it (smile) It means you are using (or at least trying out) our software. Anyone can submit a bug report into our issue tracker system JIRA http://dev.sourcefabric.org. Keeping low the amount of invalid issues and creating well-written tickets is something that you can do that will help a lot the Quality Assurance team and core developers. To do so, please consider the following pointers: Before creating a ticket • Verify if someone else has already reported the same issue. You can do so by searching in JIRA. Do not give up with the first try, you can use JIRA’s advanced search. Keeping JIRA as clean as possible by avoiding duplicates is really important for us. • If you find there is already an open ticket reporting the same issue, please contribute by adding as much infor- mation as you can, especially if you think it would help us to easily reproduce the problem. • Do not create a ticket if you are not certain the issue is a bug. Ask in the forums. Our developers are constantly following conversations and answering questions. • Do not use JIRA to ask questions, that’s what the forums are for. When creating a ticket • Well-written reports are extremely important. By doing so you are helping us to easier understand and reproduce issues, and get processed more effectively. • A few hints for what we consider a well-written bug report: - Report only one issue per ticket. Including different issues in the same report will make things less readable and much harder for us. – Provide a complete, concise and clear description of the issue. – Provide a set of detailed steps to reproduce it.
3 Development @ Sourcefabric, Release 0.1
– Provide details on the specific platform you are using: browser and browser version, operating system, Web server setup, etc. – Provide as much relevant extra information as possible (e.g. stuff like messages from error logs and exception backtraces.) • There is no need to notify in the forums that you have reported a bug. Every time you create a new ticket, core developers are automatically notified. Once you have created a ticket into JIRA, more likely you want to know what will happen next. Here you can read how we process a ticket and understand its lifecycle.
1.2 Requesting features
In Sourcefabric, we are always looking for ways to make the software we produce better, and contributing ideas is an essential part of this process. Here you will find how to effectively submit feature requests. • In our issue tracker, for each of our projects, you will find a milestone called User Requests. Creating a ticket in User Requests is the way your idea will get more attention. The Project and Innovations teams in Sourcefabric keep an eye and manage all submitted requests. • The more information you provide the better. Describe clearly, as part of the description of the ticket, what exactly the feature is about and why you consider it to be interesting and useful. Providing a set of use cases is always helpful. • Pay attention to the related ticket you created in the issue tracker, our development team will likely start a conversation and give you some valuable feedback. • If the feature gets accepted it will be pushed to the roadmap and develop for one of the upcoming major releases. • If you are a programmer and you want to implement the feature yourself, that will make us happy (smile) Code contribution is always welcome. Follow the guidelines here: Writing code. • If you have already started working on the feature, show us your code! Good code speaks better and gives you the best chance to get it accepted.
1.3 Writing code
Joining the community of developers and contributing code is a great way of meeting some other talented developers, making your work more visible and developing your skills further while having a bit of fun too. You found a bug? have a great idea? Go to our issue tracker and create a new ticket. You may also consider picking an existing issue. When writing your code you should stick to these coding standards, following those will give you a better chance of getting your code accepted and included in our products. In a general way, contributing code to any Sourcefabric project –whether a new feature or a bug fix- is simple and goes like this: • Fork and clone the project repository in GitHub. • Work on the code and push back to your fork. • Submit a Pull Request whenever ready. To know precisely how to commit your code, check Working with Git and GitHub.
4 Chapter 1. Contributor’s Guide Development @ Sourcefabric, Release 0.1
1.3.1 Coding Guidelines
Python styleguide todo
PHP styleguide todo
Javascript styleguide todo
Database naming conventions todo
1.3.2 Unit Testing
1.3.3 Submitting patches
1.3.4 Git and GitHub Pull Requests
Here you will learn how to contribute code to any of the Sourcefabric products. The short version is: do it via GitHub Pull Requests. In the Sourcefabric Development Team we use Git as the revision control system and source code management tool, and GitHub to manage the code committing cycle for all Sourcefabric Products.
Note: This page is not intended as a GitHub guide. GitHub provides already a fairly good bit of help that you can always consult.
We are glad to receive your contributions in some other ways, especially if you have decided not to be a GitHub user. Submitting GitHub Pull Requests though makes the job of the core developers a lot easier, for example when reviewing the code, and increases the likelihood of getting your contribution merged into our products.
Installing and Setting up Git
You can download Git and get it installed, but you better do that with the help of your Operating System’s software manager, it is always easier (wink) Once you have installed Git, the first thing to do is to tell Git about your name and e-mail address. $ git config –global user.name “Your name” $ git config –global user.email “[email protected]“ Set user.name to your real name, not your GitHub nick or any other nick name. The email address you set for user.email must match your registered address in GitHub, as this will be used to associate your commits with your GitHub account.
1.3. Writing code 5 Development @ Sourcefabric, Release 0.1
Getting ready
Before writing your code you must have setup your work environment. This is done in three simple steps. Let’s assume your GitHub account is johndoe, and that the Sourcefabric project you want to contribute to is Superdesk. The first thing to do is to fork the Superdesk repository in GitHub, so: • Login in your GitHub account • Go to the Superdesk project space in GitHub • Look for the button labelled Fork and click on it You have now in your GitHub account a replica of the Superdesk repository, that is your fork and lives only in GitHub. Now you need to download the source code so that you can work locally in your own computer. Open a console and type in this: $ git clone [email protected]:johndoe/Superdesk.git This will create a new directory Superdesk in your current working directory containing a clone of your GitHub repository. This clone has by default a single remote called origin, that points to your fork on GitHub. Your local copy of the Superdesk project is tracking your GitHub fork, but what about the original Sourcefabric repository? It is really important to track the original project, otherwise you wouldn’t get the updates from all the other developers that get merged into upstream. $ git remote add upstream https://github.com/sourcefabric/Superdesk.git $ git fetch upstream The new remote is called, in this case, upstream. You can call it anyway you want, we call it upstream because that’s what it is, plus it is a common practice to use that name.
Working on a ticket
Create a new branch any time you will start working on a ticket, and create it branching off of upstream/master. $ git checkout -b ticket-xxxxx upstream/master You can also create a branch based on a different branch than master, for example when working on a bug fix for a release branch, let’s say 1.2 $ git checkout -b ticket-xxxxx-1.2 upstream/1.2 Do your work and commit to your local branch (remember to follow the
Pushing your stuff to GitHub
When you consider you are done with the task...
1.4 Documenting
Documentation is treated in Sourcefabric in a way that it is as important as writing code. We do care about writing software in the best possible way, but that is not enough. Writing precise documentation is the most natural mean to
6 Chapter 1. Contributor’s Guide Development @ Sourcefabric, Release 0.1 make the software easier to be adopted, and we try to do so. Documenting though is in a way similar to coding, as you need to invest time on structuring, composing, testing, fixing, updating, etc. You can help us in all this process in a few different ways: • Documenting new features • Translating • Fixing issues • ... and the simplest yet important, reporting issues This guide aims to provide all information ...
1.4.1 Format todo
1.4.2 Standards todo
1.4.3 Getting started with Sphinx and reST todo
1.4.4 Documenting new features todo
1.4.5 Improving existing texts todo
1.5 Localizing
Having our software translated into as many languages as possible has always been a philosophy within Sourcefabric. Localizing software is a time-consuming task though and...
1.6 Helping others
One of the most underrated ways of contributing is the ability to help others. We have an important base of users for all our products, and we feel bad because sometimes we cannot answer users’ questions as soon as we wish, just because we are focused on delivering the best software we can. Either if you are a user of, let’s say, Airtime or Booktype, we invite you to participate of our forums no matter how. Asking questions, providing help to others by answering questions.
1.5. Localizing 7 Development @ Sourcefabric, Release 0.1
8 Chapter 1. Contributor’s Guide CHAPTER 2
Developer’s Guide
2.1 Git repositories
Whenever you want to work with any of our products either for trying in-development features or contributing to development, you will need to get a copy of the source code. You do so by cloning the corresponding Git repository. Here you will find all the necessary information on how the Git repositories are organized, so you know where to look for stuff.
Usage in production If rather what you want to do is to setup and deploy a system to run in a production environment we highly recommend getting an official release package. The source code as it is in the Git repositories goes always through a building phase that prepares it to run as expected. We cannot guarantee the same results otherwise.
2.1.1 The short version
In Sourcefabric we use Git as management system for the source code. You can find all official Git repositories hosted in GitHub at https://github.com/sourcefabric/. The branching model we follow in Sourcefabric aims simplicity. It considers three different types of branches: • main development branch (a.k.a. master): the base for almost all development. Every time you will start working on something new, you should do it based on master. • release branches: officially supported versions of the product are kept in release branches, this is mainly for maintenance. If you want to contribute a fix to a bug that affects any of the supported released versions, you should do it against the corresponding release branch. • feature branches: when a new major feature or improvement is being done, likely work happens in a feature branch to not affect master directly. Every release can be found in our repositories in the form of Git tags. If you find this short version not enough to understand the model, please keep reading.
9 Development @ Sourcefabric, Release 0.1
2.1.2 Branches in detail
The master branch master is the main development branch. This is the code to base new features, major improvements and re-factoring on. It holds the code that will constitute the next grand or major release. • master, being the main development branch, is the only one permanent branch in the repository, it will be always available and won’t be never removed. All other branches have a lifetime, they are created and deleted when not needed anymore. • master is an active development branch, therefore it is not considered to be in a stable state. • However, supported in our development workflow, master can be considered to be always in a good functional state. • master triggers either a grand release or a major release, only.
Release branches
These are development branches for the officially supported versions of the products. • Every officially supported version of a product has a corresponding release branch. • Lifetime of a release branch is determined depending on whether the version is officially supported or not. When a released version is not officially supported anymore, the corresponding release branch is removed from the repository. • Bug fixing usually happens here, and then –if apply- the fix is ported to master. It can also be done the other way around, important is to make sure that the fix will be available for all affected branches. • NO new features are ever added to a release branch. • A release branch triggers always and in all cases the next minor release, only. • Whenever a release needs to happen, a new release branch is created branching off master, and when doing so ALL new features added since the last release will be part of the new release, this means you cannot cherry pick which features will make the new release. • Branch naming convention:
Feature branches
Implementation of new big features, experimenting features, major improvements, re-factoring and re-writing, are made in separate feature branches. • Whenever an enhancement is required, it is done in a specific branch, branching off master. • Lifetime of feature branches goes from the moment where the implementation begins till the moment when the branch is merged back to master. Once that happens the feature branch may be removed from the repository. • A feature branch never triggers a release. Features are always merged back to master in order to be released. • Branch naming convention:
10 Chapter 2. Developer’s Guide Development @ Sourcefabric, Release 0.1
2.1.3 Released Versions
Officially released versions are available in the form of Git tags. Every time a new version is released, a new Git tag is created, using the following naming convention: v
2.2 Testing
2.2.1 Travis-CI todo
2.2. Testing 11 Development @ Sourcefabric, Release 0.1
12 Chapter 2. Developer’s Guide CHAPTER 3
Overview
3.1 Release process
Note: In this section you will learn how releases work in a general way at Sourcefabric. Be aware this may vary from one product to another to suit particular needs.
3.1.1 Official versions
An official version is a version of the product that has been publicly released. There are three different types of versions depending on the magnitude and characteristics of the changes: grand, major and minor. Grand releases happen very infrequently, and in most of the cases represent large, sweeping changes to the product. Major releases happen in general every few months, this is product specific though as each product has its own roadmap. A major release will include usually new features, improvements to existing features, and such, together with a set of bug fixes. Minor releases (a.k.a. maintenance releases) happen at least once between major releases, and probably more often if required. Minor releases will be 100% compatible with the associated major release. A minor release includes only localization updates, bug and security fixes.
Version numbering
Sourcefabric products which define an API from their very first version follow the semantic versioning convention (e.g. Liveblog, Superdesk.) Other Sourcefabric products (e.g. Airtime, Booktype, Newscoop) use the following numbering conventions for re- leases: • Versions are numbered in the form A.B or A.B.C. • Grand releases follows the convention A.B, where B is always a zero (e.g. 1.0, 5.0, etc.) • Major releases follows the convention A.B, where B has always a positive value that increments by 1 (e.g. 4.1, 4.2, etc.) • Minor releases follows the convention A.B.C (e.g. 1.5.2, 1.5.3, etc.) • A represents the grand version number, which is only incremented for dramatic changes to the product, and these changes are not necessarily backward-compatible. That means, for example, code you wrote for Airtime 2.1 may break when we release Airtime 3.0.
13 Development @ Sourcefabric, Release 0.1
• B represents the major version number, which is incremented for major yet backward-compatible changes. Using the same example; code written for Airtime 2.1 will continue working under Airtime 2.2. Exceptions to this rule may occur and will be accordingly documented in the release notes. • C is the minor version number, which is incremented for bug and security fixes. A new minor release will be 100% backward-compatible with the previous minor release. In some cases, we make alpha, beta, or release candidate releases. These are of the form A.B-[alpha/beta/rc]N, which means the Nth alpha/beta/release-candidate of version A.B.
3.1.2 Supported versions
Supported versions refer always only to major versions, e.g. Newscoop supported versions (at the moment of writing this): 4.0, 4.1 and 4.2.
3.2 Security policy
14 Chapter 3. Overview CHAPTER 4
Community
4.1 Community
4.1.1 Updates todo
4.1.2 Support todo
4.1.3 License todo
Note: This documentation is under development. Please refer to the links on the sidebar for more information, or to get in touch with the development team.
15