Like my Twitter Avatar plugin, even my WP Github Gist plugin was broken recently due to changes in the underlying API that my plugin was using. This time it was because of the changes in the Gist Embed API.
Tag Archives: github
After that, this past one month has been really busy. I guess instead of me explaining how busy it had been, I guess the following picture would give a better idea.
There were 70+ commits that got into the project and huge number of critical bugs got fixed. If you look very closely, you will also find that it’s not just me who have been doing this 🙂
I always believed that github encouraged contribution to projects, but in the last one month I also learned a couple of new lessons on how you could encourage more participation and contribution to your open source projects.
Below are some of those learnings. Do take them with a pinch of salt though 😉
Let people know that they can contribute
This might seem silly, but it is really important to let people know that your project is open for contribution. I have spent countless hours fixing bugs and sending pull requests to projects in github, only to know that the repo owner is not interested in contribution 🙂 And it is still worse, when they just decide to be silent about it, without even leaving a small comment.
So let people know upfront whether you will be accepting contributions or not. You don’t have to write huge paragraph about it. Just a single line, which says “contributions are welcome” in the readme file should do it. I generally add some variation of the following in my projects.
All contributions (even documentation) are welcome 🙂 Open a pull request and I would be happy to merge them.
Let people know how to contribute
The next thing to do is to let people know how to contribute. The following are things which you might have to let them know.
- Which coding style they should follow
- Tabs vs space or 2 vs 4 character indent or to have a semi-colon or not 😉
- Whether they should open a pull request or send you a patch/diff
- Whether all pull requests should contain test or/and documentation
- How they should word the commit message. I try to follow this guide by Tim Pope
- Whether you need them to have multiple commits or one single commit
You could choose your own process, but keep in mind that the simpler the process the easier it is to follow it. I generally follow a very simple process and reword or change the commit message if needed.
One other thing, you might have to keep in mind is that, not everyone is comfortable with git/github. In those cases, I point them to the guide that I wrote to help people contribute to github projects.
Track feature requests and TODO’s
Sometimes people want to just get their hands dirty by contributing a simple fix or feature before they become comfortable. In order to help people get started I track all feature requests and TODO’s in github issues. I also use TODO comments in the code and if applicable also link it to corresponding github issue. I also add the following line in the readme file.
If you are looking for ideas to work on, then check out the following TODO items or the issue tracker.
In addition to helping people who want to contribute, this also helps me to keep track of issues and features for the projects. If applicable also try to create milestones and assign issues and feature requests to corresponding milestones. This will also be useful for users of your project, to know when to expect a feature to be implemented.
Respond to pull requests
If someone sends a pull requests or reports an issue, try to respond to it. When someone creates an issue or pull request, they have spent their free time and you should respect that fact.
Sometimes you may not be interested in accepting the pull request. In those cases at least let them that you can’t accept it and also let them know the reason why you don’t want to accept it.
Eventually, you will receive a pull request which is just plain stupid. Even in those cases try to be very polite.
When people are just getting started they may miss out something and might make mistakes or may not understand something which will look too trivial. But if you are going to embarrass them or be hostile, then it is not going to be helpful for them. They might just stop contributing not just to your project but for any project. Be polite and encouraging, especially if they are just getting started and you might make someone’s day a little brighter 🙂
Also leave a simple “Thank you” comment after you merge someone’s pull request. It is a little mark of respect that you show for someone who has taken an effort to fix your code.
Follow a proper versioning policy
Any project which will be used by more than one person needs a proper versioning. These days I have started to follow Semantic Versioning for most of my projects. It is very simple to use and very effective.
Show people how to do it, by doing it
Whenever I want to contribute to a project, I try to get a sense of how things are done by seeing the commit history. So if you want people to follow a certain process or style when they contribute, then you should follow it in the first place.
Hide your time machine 😉
.. and don’t forget to hide your time machine 😉
Sometimes a little humor in your comment to a issue might make it easy for you to communicate with someone on the other side of the globe.
Happy coding 🙂
After looking into my github account, lot of people used to ask me why I open source my pet projects, especially after looking at my streak at github (my current streak is at 52 days 😉 ) the frequency of the question has increased.
I used to come up with an answer by combining these words randomly (passion, show off, free, rebel, linux, anti-Microsoft, license). But today, I realized that there is another (more important) reason why you should open source your (pet) projects.
Your project might have a longer shelf life than your interest in the project and in some cases longer than your life itself.
You might lose interest in the project, but if you have open sourced it, then there might be someone else who will continue to maintain it. But instead if you had just kept it in your hard drive, then it will just become part of the cosmic dust.
I have read about many examples where projects are continued to be maintained by other people, when the original creator has lost interest. _why is one famous example. When he suddenly went offline in Aug 2009 people immediately started creating mirrors of his projects and even though he is no more (in the online world) his projects are still being maintained actively.
None of this would have happened if he had not open sourced his code.
Let’s talk about the project that thought me this.
Sometime back, I came across a post which explained how you can program Arduino from command line by using a makefile. I immediately got hooked and started using it when even I was working on Arduino sketches.
Soon I found out a couple of issues and submitted pull requests. Some of my pull requests were accepted and others weren’t. While browsing through the issues and pull requests of the project in github, I found that there were lot of other people who have also contributed various patches to the project. It also seemed that the original author has stopped doing any development or answering pull requests.
I started to consolidate all pull requests and patches from various forks into a common fork and even updated the readme file expressing my desire that one day all these changes would get into the main repo 🙂
Fast forward a couple of months.
Last week, I was surprised to receive an email from the original author, saying that he has lost interest in the project and whether I would be interested in maintaining the project going forward. I happily accepted and he transferred the repo to my account, after I merged all my changes back into the main repo.
None of this would have been possible if he didn’t choose to open source the project initially and also let go the project when he lost interest.
Thanks to Github
Ohh, by the way, I should also mention that some of it was possible only because of github. If github wasn’t there, then it would had been difficult for me to find and consolidate other forks and he also wouldn’t have noticed my fork or the effort that I was spending on the project.
Also, the recent addition of redirects by github made the repo transfer really seamless.
So remember to open source your pet projects by at least uploading them to github. Because you may lose interest in the project some day, but the project might still continue to live long after that.
Happy Open sourcing 😉
Until recently I was using the official WordPress repository’s svn to do the development. All my non-WordPress pet projects are hosted in my github account.
I was thinking of moving all my WordPress Plugins to github for quite sometime now, but didn’t do it thinking that it might involve huge effort to keep both the repos in sync.
After reading about how a couple of people moved (and didn’t face much problem afterwards), I decided to try it out for a couple of my Plugins. The following is what I did and in the end, figured out that it was worth the effort.
Github – more than just code
To be fair to official WordPress Plugin repository, there is nothing anything wrong with the way it works or with svn.
It is just that github as a platform is more suited if you are interested in collaboration and receiving contributions from users. It reduces the barrier to entry for people to contribute to projects and also it provides enough tools for project owners to easily merge (or reject) contributions from users.
I was more interested in this aspect of github rather than the ‘git’ part.
Using github for hosting WordPress Plugins
When I decided to move from svn to github, I wanted to do the following things.
- I wanted to maintain the entire check-in history from svn. Some of my Plugins are more than 4 years old and have gone through lot of revisions and I didn’t wanted to loose them.
- I also wanted to do the development in github (read doing atomic check-ins) and then upload to WordPress repository only when I tag the changes for release after testing them.
- I also didn’t wanted to manually check-in in both the places to do the sync.
For the first I found that
git-svn can fetch all the check-in history.
For the second and third point, keeping pragmatism in mind, I ended up creating shell scripts so that I don’t have to do anything manual.
You can get the scripts that I wrote from my github account. The project consists of two scripts.
- clone-from-svn-to-git.sh – Use this script to clone your WordPress Plugins from SVN into git/github
- deploy-plugin.sh – Use this script to push your WordPress Plugin updates to SVN from gi/github
Right now the documentation is pretty sparse. I will fix it when I get some free time 🙂
Things to improve
The scripts pretty much do the job. Going forward, I want to improve the following to make it more useful.
readme.txtfile used by WordPress repository is not fully in markdown. Because of which the readme file displayed in github is slightly broken.
Ability to auto update the
.potfile before releasing the new version
WordPress repository allows you to add a banner using the
assests/directory. Need to add support for that.
Update: All the above features are added. Check out the latest code in github.
Is it worth the effort?
So far I have moved the following Plugins to github. Will be moving the other ones as well when even I get some free time.
- Bulk Delete
- Bulk Move
- WP IRC
- WP Github Commits
- WP Plugin Reviews
- WP Year end stats
- Posts By Tag
- Email Log
- Twitter Avatar Reloaded
So now the real question. Is it worth the effort? It is worth every second that I spent on it.
You should check the pull requests I have received so far. I have received more contributions to my Plugins in the last couple of weeks than the last 5 years 🙂
If you are a WordPress Plugin developer, then try out my script and let me know if you have any feedback.
As most of you know, I host most of my projects which I have released as open source in Github. I am open for collaboration and generally accept most of the pull requests that people send me.
Recently I noted that not all people who want to contribute are proficient with git or Github. So here is a small guide to help people who are interested in contributing to projects hosted at Github.
Before we proceed just keep in mind, that this is not the only way to do it. But if you are just starting out using git or Github, then this is a good starting point.
Fork the project in Github
The first step is to fork the project at Github. Go to the project that you want to contribute to and then click the fork button near the top right corner.
Clone the forked project to your machine
When you fork the project, Github creates the forked project in your account. Once you forked the project, you need to clone it to your machine.
You can use the following command to do it.
git clone email@example.com:sudar/wp-irc.git
Replace it with your actual username and project name
Create a new branch
The next step is to create a new branch. You can use the following command to do that.
git checkout -b branch_name
Commit your changes
After you have made the changes, you have to commit them to the new branch
git add file_name
git add -p file_name
git commit -m "Your commit message"
Remember to have a meaning full commit message. If possible follow this guide by Tim Pope on how to construct a good commit message.
Push the change to Github
Next you have to push the changes to Github. You can do it by using the following command.
git push -u origin branch_name
Send a pull request
Now go to Github and send a pull request, by clicking the pull request button in Github. The owner of the repo will be notified and he may choose to accept or reject the request.
Keeping your repo upto date
Once the pull request is accepted, you can merge the changes back to your repo by using the following commands.
git remote add upstream git://github.com/sudar/wp-irc.git
git checkout master
git pull --rebase upstream master
git push origin master
Recently while debugging the issue with my WordPress feed, I found out that the Plugin which I was using to display files from my Github Gist was highly unoptimized. As promised, I created a Plugin to do it properly.
While working on this new Plugin, I felt that it would be really nice to embed Github files as well in addition to embedding gist.
My search lead to a Google app engine based solution called Gist-it. I really liked it, but one problem with it was that it was not supporting embedding particular regions of the file. So during the Yahoo HackU last week, I hacked on it and added support for specifying line numbers.
I also updated my WordPress Plugin to support gist-it urls as well.
Download & Usage
You can download the latest version of the Plugin from the Plugin’s home page. The Plugin’s home page also has detailed examples of different ways by which you can embed gist or Github files in your WordPress blog posts or pages.
If you have any comments or if you want to report any bugs, please leave a comment below.
I would be posting updates about this Plugin in my blog and in Twitter. If you want to be informed when new version of this Plugin is released, then you can either subscribe to this blog’s RSS feed or follow me in Twitter.
Recently I got an email from my friend Sudheer, saying that the feedburner feed of my blog is not working. I thought it might be some small issue, but it took me more than a couple of hours to fix it. As usual, I thought of documenting it since it was an interesting problem and also someone who has the same problem might also find it useful.
WordPress feed timeout
I started the debug process by logging into Feedburner dashboard. Feedburner reported that it is not able to fetch my blog’s feed url. When I tried to open the feed url directly in browser it was loading, but it took a couple of minutes for WordPress to generate it. But both feedvalidator and feedburner said that the feed times out.
My website was loading properly and my error log was empty. I tried lot of different things but was not able to figure out why the feed was timing out.
Increasing memory used by WordPress
After a couple of web searches, I landed on a old forum thread, which stated that we should try to increase the amount of memory used by WordPress. I tried doing that as well, but it didn’t make difference 🙁
Reducing post count in feed
Then I tried to reduce the number of recent items that were shown in my feed to 10 from the default value of 25. The feed was getting generated in some decent time and was able to let feedburner pick up my feed. But it still didn’t solve my original issue.
After some more debugging, I found the root cause of the issue. An unoptimized Plugin was the real culprit.
I was using github’s gist to store the code samples that I use in my blog posts and used a Plugin to embed the code directly from github. The advantage of this approach is that, there is one centralized repository for my code samples with versioning and also github provides nice syntax highlighting.
The Plugin was making curl request to github to retrieve the code sample and it so happened that most of my last 25 blog posts had code samples and some blog posts even had around three code embeds.
The problem with the Plugin was that, it was not using WordPress’s built-in HTTP request object and also it was not caching any of the response that it got from the curl request. I quickly rewrote the Plugin and WordPress was immediately able to serve the feed in less than a second. (
Will be releasing the Plugin pretty soon) Update: You can find the Plugin in its homepage
So if you are also facing timeout issues with your WordPress feed, then try the following
- Try increasing the memory used by WordPress
- Try reducing the number of blog posts that are disabled in your feed.
- If nothing works, then it’s mostly because of some unoptimized Plugin.
I wanted to visualize data using graphs in one of the Android app that I was developing and found that Android SDK don’t provide a good graphing API, which you can use out of the box.
You have to either using Canvas 2D graphics to draw your graphs from scratch or use some commercial components.
If you can assume that some form of Internet connection will be available then you can use Google Graphs API to get the graph and embed it in a webview control. But I didn’t wanted to make that assumption and so I started to search for a good graph component, which I can use in my app.
So I wrote a sample app to try it out and it really worked out great. I thought of posting the source code and a little writeup about it so that it would be useful for others as well.
Setting up webview
The first thing that we have to do is to setup webview, which will be rendering the HTML page, on which we will be drawing the graph. You can add the webview control to your android layout.xml file using the following code.
Once it is added to your layout.xml page, you can access it in your activity using the following code.
Adding the HTML page to assets folder
Also add the flot and jQuery files into the /assets folder and refer to them with relative urls in your HTML file. You can also checkout the HTML file that I have created for reference.
Once you add the HTML file, you can load it in your webview using the following code snippet.
Check out the StatsGraphHandler class in my sample project for reference.
Enjoy your graph
That’s it 🙂 Fire up your app and you can see the excellent graph generated.
You can also add some buttons in the HTML page, which can directly interact with the graph. For other options, check out flot’s documentation.
You can download the complete code of the sample app that I created from my github account.
The following are some of the features of the Plugin
- You can choose whether to show the ribbon on the right side or on the left side.
- You can choose any one of the 6 different colours that are available.
- Configuration can be set either globally or on a post by post basic.
You can see the Plugin in action in my blog. In case you are viewing this post in a feed reader, then this is how it looks on my blog.
This is how the configuration box looks in the Write page/post admin page
You can download the Plugin from the Plugin’s home page.
As usual try out the Plugin and do let me know if you have any feedback, queries or comments.
I got introduced to Git and Gitbub by Yuvi and ever since I have been hooked up. I have started using it for all my pet projects. I even convinced Steve Bruner so that I can use Github for RoloPress. 🙂
Over the years I have released lot of code out in the wild and I thought of consolidating all of them in Github, so that it can be of use to someone who might need them. At last I found some time and uploaded most of them to my Gitbub account.
Below is the description of some of those projects which are currently there in my Github account.
I created this project to share my homework and the sample code used in the “Developing Android Applications in Java” online class, which I am currently following.
RoloPress core and RoloPress Default
These projects contain my contribution to RoloPress, a WordPress based contact manager. You can read more about WordPress from its homepage.
FeedBurner – stats
FeedBurner-stats is a Google Gadget which allows you to keep track of your Feedburner subscriber count. It uses Google Chart API and Google Gadget API.
Bloglines Notifier is a Google Gadget which will notify you the count of unread items in your Bloglines account. (Hope someone is still using Bloglines 😉 )
It is a fork of John Resig’s retweet script which I am using in my Easy Reweet WordPress Plugin. I have added a new feature to this script which allows you to associate the list of urls created to your bit.ly account.
It’s a small Ruby script which prints the number of words (with their count) present in a given text file
It is a small Ruby script which unrars all files found in all the subdirectories of a director given in the command line.
I am still undecided about porting my WordPress Plugins from the official WordPress Plugin repository to Github. I guess it is better to have my Plugins in the Plugin repository for now.
Update (Feb-2013): I have now started to use github for my WordPress Plugins as well.
BTW feel free to fork any of these projects and I would be happy to pull in your changes if you have added some enhancements to them. 🙂