Recap of the February Pinax Hangout
The purpose of the Pinax Hangouts is to engage more with the Pinax community. We want to let you know what we are working on, answer your questions, and present demos of old and new apps and starter projects. Our host this month was Patrick Altman. Patrick talked about contributing to Pinax.
Issues
Finding The Right Issue to Work On And Filtering Issues By Labels
We recently started creating so called first-timers-only issues. These issues are issues, which are fairly easy to tackle, provide detailed instructions of how to solve the issue, and offer mentorship. The purpose is to give someone who has never contributed to open source before a chance to make their first open source contribution.
We also started assigning the labels difficulty: easy, difficulty: medium, and difficulty: hard to our issues in order to communicate clearly how difficult each issue is to solve. If you’d like to find out more about our new labels, please read this blog post.
We have a few first-timers-only issues for pinax-blog at the moment. If you go to the pinax-blog repository on GitHub, then click on “Issues”, then on “Labels”, you can filter the different issues by labels according to what kind of issue you are looking to work on.
Issues will have varying degrees of conversation that is happening on them. If things are not clear, please leave a comment and ask for more directions, or ping us about it in Slack.
When Should You Create An Issue?
In general you should create GitHub issues for reporting bugs, requesting features, etc. If you have a question or would like to discuss something with us, we’d prefer for you to ping us in Slack. We are usually able to answer questions and help you faster, when you ping one of us in Slack. This is not a hard line however. If you can’t or don’t want to use Slack, you’re of course welcome to ask a question in a GitHub issue. We would rather have you create an issue in GitHub, even if it’s a question or you’re not sure whether you should create an issue or not, than to not bring it up at all. If you’re not sure whether you should create an issue, please jump on Slack and ask us.
Pull Requests
Walkthrough: Creating a Pull Request for django-user-accounts
django-user-accounts is an app that provides sign up, log in, email confirmation, and other features around account management and authentication. In order to show you how to make a pull request, we want to work on issue #106, which is about moving callbacks into hooksets. We use hooksets in a lot of our apps to provide a way to override functionality at a site level. Callbacks is a way we used to do this. Solving this issue will mostly involve cleaning up some old code and putting it in a new place. The code itself is not important, we just want to show you how you can find something that you want to contribute to. It could be something that needs to be fixed, but it could also be something you want to add.
We want to work on issue #106 so we need to fork the django-user-accounts repository to our own account so we can then clone it, which means pulling the code down to our local machine, doing some work on it, pushing it back up, and then creating the pull request. First click the “Fork” button in the top right corner. It will ask us what account we want create it to so we have to choose an account. We now have a fork and can do the clone next. Before we clone the repository we should create a folder for it to be cloned into on our machine first, we can do so by typing $ mkdir pinax into our terminal. By typing $ cd pinax into the terminal, we make sure to switch to that folder. Next we should create a virtual environment $ virtualenv pinax and activate it $ . pinax/bin/activate. If you now see $ (pinax) in front of each line in your terminal, you know that your virtual environment has been activated. We can now go ahead and clone our repository. In order to do so we need to copy the HTTPS link (next to “New file”, “Upload files”, and “Find file”), then go to our terminal and type in $ git clone followed by the link and hit enter. The repository will now be cloned onto our machine.
Next open your text editor and open the cloned repository in your text editor so you can work on fixing the issue. Since the purpose of this Hangout was solely to show how to make a pull request, we’re leaving out the code that fixed issue #106. If you’re interested in how Patrick fixed the issue, we recommend for you to watch minutes 12:30-15:10 of the video.
After fixing the issue we’re ready to commit, so let’s go back to our terminal. To check which branch you’re currently on type in $ git status. It will show you that you’re still on your master branch. It’s better to push your changes to a different branch, not the master branch, this will keep your commits clean, so let’s create a different branch which we’ll call callback-cleanup:
$ git co -b callback-cleanup
When you type in $ git diff, git will show you the changes you made to the code so you can review them before committing your code. Now you’re ready to commit your code
$ git commit -am "your commit message“
Mention in your commit message which issue this pull request closes. When we reference the issue, once we create the pull request, it will attach to that issue. For more tips on how to write good commit messages, please see the “Writing Commit Messages” section here.
We committed our code, now we need to push this branch up to our fork
$ git push -u origin callback-cleanup
-u will set up tracking for this branch. We are going to push it to the origin, which is our remote, and add the branch name, which is callback-cleanup.
Now that we pushed our code we can go back to GitHub to the pinax/django-user-accounts repository, not your fork of it, then click on “New pull request” and on “Create pull request”. Click on “Compare across forks”, select the branch you want to create a pull request to and your branch that you pushed the changes to. It will show you a summary of your changes, which you can review. If you forgot something you can create another commit and push it up to that same branch. GitHub will take your commit message of your last commit as the title of the pull request. You can leave it as it is for a pull request like this one but when you create a pull request that doesn’t have an issue associated with it it’s preferred if you would describe what exactly you did, why it’s important, etc., which will make it easier for us to review your pull request. The more information, the better. Then go ahead and click “Create pull request”. Since Brian Rosner is the maintainer for django-user-accounts he will review the pull request and hopefully merge it. If not he’ll leave some feedback for you. Sometimes we have a question sometimes we would like to see something done in a different way, but in general we’re pretty liberal when it comes to accepting pull requests.
We love seeing new contributions. We believe the best way to learn Python and Django is to do and to make lots of pull requests.
After you made the pull request, you can see that it has automatically been linked to the issue. The issue is now going to have a tag with your pull request. When we close the pull request it will close the issue automatically. You can also see that there is a test suite which is running some tests. It will turn green once it is finished running the tests and everything looks okay. If the test fails, it’s a good idea to fix those issues and commit the fixes to your pull request. It’s much easier for us to accept a pull request if everything is green.
When the master branch changes because of other pull requests being merged or one of us doing some work on a repository, this could make your pull request unable to be merged. In that case it’s important to keep your pull request updated so it can be merged. Sometimes that just means going back to your master branch and updating it against the Pinax master branch.
In order to do that you want to copy the SSH URL from Github and paste the following into your terminal
$ git remote add pinax [insert SSH URL]
You then want to update your local master with remote
$ git pull pinax master
It should show you any updates that have been made.
You want to bring master up- to-date and then jump to your branch
$ git co callback-cleanup
Then you want do a rebase against master
$ git rebase -i master
rebase is going to pull back all of your changes, merge them in, update to master, and then replay your changes on top of what was updated on master. It will stop at the first commit that gave you a conflict. You can then fix that merge conflict and do git rebase continue until all of your commits have been replayed. Then you’re going to git push force to your remote branch. This will automatically update the pull request. You should get a green light and your pull request will be able to be merged.
How to Manage Multiple Pull Requests
If managing multiple pull requests when the first one was not accepted yet, it’s best to keep a branch off of master when you make the pull request. This will make it way easier for you and it will just be a matter of keeping your remote master updated and rebasing your pull request. When you push and update your branch, your pull request will automatically be updated, too.
How To Get Onto Slack
Got to pinaxproject.com or to blog.pinaxproject.com, then click the Slack button you will find there. Type in your email address and click “Get My Invite”. You’ll get an email within a couple of minutes which will allow you to sign up for our Slack team. You can either run Slack in your web browser at pinax.slack.com or use the free Slack client.
Getting Involved
We’re working on a big effort right now which is driving a lot of the Pinax starter projects and will drive many of our Pinax apps. This effort is the Groupware Starter Project. The Groupware Starter Project is going to be the beginning of building a learning management software functionality. We are still debating on how to petition the apps that will become part of the Groupware Starter Projects by groups but before we can do this there is a lot to be done in updating these apps to latest standards, using hooksets, and getting templates right. We are currently working on reaching Milestone 0. We would appreciate help with pinax-documents, pinax-ratings, and pinax-comments. Working on the integration tasks for our Documents Starter Project would be tremendous help, especially issues #18, #19, and #20. Milestones 1, 2, and 3 are not fully fleshed out yet but we’d also appreciate help with the pinax-forums starter project.
The Groupware Starter Project is a great place to get started. If you’re looking for something to do in open source and want to help with Pinax, this is the place to come. We also appreciate contributions to different apps if there are certain apps you have an interest in or that you work with but if you don’t know what to work on, we’d appreciate your help on the Groupware Starter Project. There’s still a lot to do and the more help the better. If this is something you’d like to help us with, please get on Slack, find @paltman, and let him know where you’d like to get started.
If you missed our February Pinax Hangout you can watch the video here
Our next Pinax Hangout will take place on Thursday, March 24th at noon Eastern time. The topic will be the Pinax Groupware Starter Project. We hope that you will join us for our March Hangout!