Introduction to Redmine¶
Redmine is a highly configurable web application focused on project management.
How to get an account¶
In order to access non-public projects and gain editing permissions (e.g to create issues), you need an account.
As soon as an administrator confirms your registration request, you get an E-Mail with login link.
Basic concepts¶
Project¶
Almost everything on Redmine happens in the scope of a project.
After logging in, you will probably see a mostly empty page. Only after selecting a project, you'll start seeing what's there.
Issues¶
This is the core module. It implements an issue tracking system, also known as Bug Tracking in Software Development or as Ticket System in a Helpdesk context.
An issue is defined by
- Subject: should succinctly explain what the issue is about.
- Description: more detail.
- Tracker: categorizes what kind of issue it is, e.g. a (Software) Bug, a Support Task, a Research Task etc.
- Status: expresses where in the (tracker specific) life cycle the issue currently is.
- Notes: useful for commenting changes, documenting progress and having conversations.
The concept of life cycle (or, in Redmine terminology: Workflow) is central to understanding issues.
Redmine allows to define custom Trackers, States and State transitions (constrained by user / group permissions). This combination allows to define Workflows which make it much easier to document tasks and collaborate on them.
(Visual) Examples for such workflows: basic, more sophisticated.
Issues can be related (linked) to each other.
A special kind of relation are Subtasks. They are used for conveniently modularizing complex issues. Issue and Task mean quite the same in Redmine terminology.
Wiki¶
The Wiki is a tool for collaboratively creating, updating and organizing project related documents.
This has some huge advantages over just having a bunch of document files on a file server:
- Low overhead, unified user interface (the same web interface for everybody instead of various desktop applications)
- Built-in versioning (example).
- Integrates well with other modules. Specific Redmine links can be used to reference issues, contacts, source code etc. Example: #29.
- Better searchability
Markdown¶
When editing text in a wiki page or issue, you see plain, unformatted text (rendered with a monospaced font).
As a non-developer, that may initially seem strange. You may be used to editors / word processors following the WYSIWYG paradigm.
The Redmine editor instead uses markup for formatting. More precisely, it understands Markdown, a popular, lightweight markup language.
You can easily learn Markdown by using the buttons on top of the Redmine text editor (e.g. for bold, italic, ...). Once used to it, you will be faster just typing it yourself. Click the blue question mark at the top right corner of the editor window in order to open this help in a popup.
A more comprehensive overview can be found here. Included are some Redmine specific instructions, e.g. for linking issues or repository commits.
Versioning¶
Versioning is a core concept for tracking and visualizing changes to documents and other content artefacts.
Since developers are lazy, they have been a driving force in automating and perfecting versioning systems.
A major step was the development of git which - although tailored for the Linux Kernel development process - has taken the Software developer community by storm and laid the foundation for today's main open source hub, github.
In Redmine, every change is automatically versioned:
On the Activity page you get a chronologically ordered list of recent changes.
Issue pages have a section labeled History which list all notes and description changes.
Wiki pages have a History button.
Versioning increases transparency (much easier for outsiders to dig in and find required context on their own), eliminates the risk of accidental loss of content (which encourages keeping content up to date and deleting obsolete one) and increases accountability (easy to see who did what, when).
Notifications¶
Redmine has a watcher system which gives everybody fine grained control about what triggers push notifications.
By default, you will get notified when somebody updates (e.g. adding a note) an issue you created.
You can change this default in the page My Account.
You can further subscribe or unsubscribe to notifications for issue or Wiki updates by clicking the Watch button at the top right.
If you consider an issue relevant for somebody, you can just add them as watcher (via the Watchers Add button in left section of the issue page). That way you know they will get informed about updates even if they don't actively monitor an issue.
According to my personal experience, this notification mechanism, when used in combination with E-Mail filters, can be quite useful for keeping track of a vast amount of activities.
Based on your needs and preferred workflows, you can sort and mark notification mails based on content.
Since they also include Headers, for example X-Redmine-Issue-Id (see source), you can build such mail filters as:
move mails reflecting issues assigned to me into IMAP folder "assigned to me" and color them red if Tracker is "Bug".
It's a powerful tool for yourself and your team which - if used in a meaningful and consistent way - helps you find the right balance between allowing individuals to work on their own schedule and without being interrupted, while making sure requests for feedback or progress updates relevant for somebody don't go unnoticed.
Don't however assume others will use it the same way as you. E.g. they may just filter out and ignore such notification mails. In order to get it working for a team, a shared understanding and commitment about if and how this notification mechanism is used, needs to be established. The more decentralized (in terms of location, time) a team, the more important this is.
Open¶
Redmine is a community driven open source project.
That means it can be (and is) self hosted, doesn't suffer of [vendor lock-in](https://en.wikipedia.org/wiki/Vendor_lock-in and - most importantly - is very extensible.
It has a plugin system and an API, making it quite easy to customize it for increasing convenience and integrating with other tools.
Source code¶
Redmine was built with Software Projects in mind. Thus it tightly integrates with VCS.
Via the repository module, git (and other) repositories can be added to a project. Example.
There's a file browser, commit history, diff views, annotate/blame views and so on - what you'd expect of a good VCS viewer. And there's even statistics.
But more important is the integration with issues. Commits related to issues are shown in the issue page, as can be seen in #24.
This makes issues an ideal tool for discussing and documenting code changes, be it features or bugs.
And because of the aforementioned laziness, commits can be associated to issues automatically by hinting it in the commit message.
Redmine looks for the string refs #<id>. E.g. the commit message great random feature, refs #24 will automatically associate the commit to the issue with id 24.
Additionally the string fixes #<id> will set the issue state of the references Bug (Tracker) issues to Resolved and implements #<id> will do the same for Feature (Tracker) issues.
In order to use a git repo:
- Go to https://redmine.d10r.net/my/public_keys and upload your public key
- Go to the repository you want to use (e.g. this) and copy the ssh URL (e.g.
ssh://git@redmine.d10r.net/lab10/fablab.git) - clone it (e.g.
git clone ssh://git@redmine.d10r.net/lab10/fablab.git. Because of the associated ssh key, it will automatically match your Redmine user.
If you want a new repository added, let me (Didi) know. The setup used here (this one) is new for me too, thus I need some more experience myself before I can include that into this guide.
More¶
For a more detailed guide, continue here.
If you have questions or suggestions, talk to Didi or go to #29.
Have fun!