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.