Documenting in the Agile world

Documentation is considered pretty un-Agilish in the Agile development world. However based on my short tryst with Agile, I feel its a necessary evil. Without adequate documentation, debugging; bug fixing and maintenance tend to become nightmares. Infact I have seen more time getting consumed by developers trying to understand other developers code than it would take to document it.
I definitely DO NOT support the elaborate documentation style that comes with Waterfall - High level designs, Low level designs and more but should be minimal enough to support the needs.

One way to do so is to add more comments than lines of code you write. This way your code would look like a beautiful story - easy to read, understand and maintain. Block comments, method comments and class level comments - all add to the readability of your code. Also this needs to be done while you are coding and not at a later stage (because that time never comes).

To document business aspect of your application you can maintain a running technical design document where in developments done in a Sprint can be jotted down for reference later on.

In these two ways you can keep your application maintenance low-cost even as it expands and still adhere to Agile's short timelines.

This post is based on my experience with Agile. Any thoughts or recommendations are welcome. Please feel free to comment. 

GIT Troubleshooting Guide

We recently moved to Git (rather E Git or Eclipse Git). The move turned out to be a bit challenging as we were among the first teams in our organisation to explore it. Hence we had to heavily rely on Google and Stackoverflow for getting past issues. Though we found most of the answers on these websites they were scattered here and there. This post aims to consolidate all those issues in one place and provide a ready reckoner for those exploring Git (via Eclipse) for the first time.

I will start with the Git Best Practices first.

Git Best Practices

1. Before starting your work, do a Git Pull.
2. Do commits often (Commit only, not Commit and Push).
3. When committing, select only the files that you have changed. (See screenshot below)
4. Before pushing your changes do a Sync with workspace. Make sure there are no conflicts with the remote repository.
5. Before leaving for the day ‘Push to Upsteam’ your changes.
6. Login to Git UI > Commits and verify if you can see your commits. Always verify your commits by going to Files tab of Git GUI and verifying if your changes are present. We came across situations where in though code got committed successfully, and also showed up in Commit tab, still files did not make it to the remote repo. The changes did not show up in Files tab either in such situations. So its always better to verify changes in Files tab.

Troubleshooting Tips

• Tip 1

Probable Cause: This error can be caused if you accidentally update invalid credentials for Git.

Resolution: Go to Eclipse>Window>Open Perspective>Git

Open <project repository>remote>origin

Click on ‘push branch’ (one with red arrow)>Change Credentials.

Verify your credentials have been entered correctly. If not correct them and then try doing a push.

If this doesn’t work then it’s probably an issue with your GIT credentials.

• Tip 2

When doing Push to Upstream you get below error:

Probable Cause: There have been other commits to remote repository in the meanwhile due to which you local repository head has fallen behind that of remote. You can also see a down arrow in your Project Explorer view indicating there are changes in Remote Repo that are not in your Local Repo.

Resolution: Do a Git Pull. This would bring latest changes from Remote to Local. In case there are no conflicting changes.

• Tip 3

When doing a Git Pull you get below error:

Probable Cause: Another developer has been working on same file as you and has checked it in before you did.

Resolution: Go to Eclipse> <file having confict>Replace With > Head Revision. This would override your changes with the one in Remote repo. Now a Git Pull should be successful.

• Tip 4

When doing a Git Pull you get below error:

Probable Cause: Your local repo’s head has got out of sync with remote.

Resolution: Team>Reset><From references choose  repo that is pointing to latest code>Mixed reset type. This would bring your local repo’s head in sync with that of remote.

Do a Git Pull, Commit you changes and Push to Upstream.

• Tip 5

Modified files not showing when doing a Commit.

Probable Cause: You probably did a Commit and Push. Though Commit was successful, Push failed due to any of the above reasons.

Resolution: Go to Git Staging View>Staged files. This would show files that have been commited but yet to be Pushed. If you see your changes here do a Push to Upstream. This would push the changes to remote repo.

• Tip 6

Resolving GIT merge conflicts (A conflict is shown by red arrow as shown below)

Probable Cause: Multiple developers working on same file simultaneously.

Resolution: Go to file having conflict>Team>Merge Tool. Resolve the conficts, then Add to Index and do a Commit followed by push. Now a Git Pull should happen successfully.