Preparing for and undertaking a platform migration


Migrating your community from one platform to another can be a daunting task. If you are planning a switch to Discourse, here are some tips to help things go as smoothly as possible.

Early communication

The biggest hurdle to overcome when migrating your community to another platform is fear of change. No one likes the unexpected, especially when it comes to a community that they feel invested in. You can mitigate this by briefing members on the upcoming transition in the weeks (or months) beforehand. In my experience, they will react a lot better if they know and are mentally prepared in advance for the shift. Let them voice their feelings and be part of the journey. Manage expectations firmly so that they know that the decision has been made, but give them the opportunity to be heard.

Highlighting some of the positive changes they’re going to see is a good approach. If there are compromises, talk about those too and explain your rationale. It might be helpful to suggest they head to so they can have a play with the software – familiarity will help to make the transition smoother.

Reevaluate existing practices

One of the potential traps when migrating platforms is to try to exactly replicate what you had before. I’d recommend using the opportunity to reevaluate your needs. Look at your information architecture. Do you need all those sub-forums or could you improve performance by using tags? Are your old moderation procedures still the most effective way to do things? Perhaps you could crowd source some of them using flags and trust levels so that your moderation team can work on more proactive tasks.

Beta test

On-boarding your moderation team (and potentially key stakeholders or superusers) early in the migration process is a great way to test and gather feedback before launching. It prepares them to support the wider community down the line and means they will be able to help you positively advocate for the upcoming change.

On a technical level, having moderators and superusers beta testing makes it far more likely you’ll catch any issues before you launch. Beta testing with just your CM or management team means that only their daily routines will be tested.

Use a checklist

Make a checklist of data to verify after the migration. Are categories and subcategories organised as expected? Are private areas still hidden? Have images and attachments come across? Is code still formatted correctly? Here is an excellent pre-launch migration checklist from @neil

Pre-empt potential barriers to entry

The whole concept of user identity in Discourse (and the primary way we link accounts) centres around email address. People tend to have multiple email addresses these days, so it’s a good idea to prompt users to think about what email address they used to sign up for the forums in the first place. If they wait until you’ve migrated and then have trouble logging in because they’ve forgotten which address they used or no longer have access to it, that initial difficulty can taint the entire experience.


Don’t launch on a Friday! Make sure you flick the switch at a time when you’re not under pressure. You need to be available to mitigate any issues, answer questions, hand hold and wave the flag. I’d suggest doing it early in the week if possible. Things can take a few days to settle.

It can often be helpful to globally pin a topic with links to the places that people use most frequently. Make your CTAs clear and don’t be too verbose. This banner shouldn’t be about marketing, it should be about orientating.

Consider starting a dedicated topic to keep all feedback in one place. Don’t panic about complaints for the first few days. Let members settle in and find their way around. Respond to ‘how-to’ questions and constructive feedback but don’t get into debates or use defensive language.

Provide a reasonable timeframe for fixing bugs and make sure you stick to it. Managing expectations is crucial at this point so don’t promise things that may not happen.

Consider redirects

Most Discourse migration scripts generate a list of 301 redirects but it would pay to double check with your engineer. You can then use Webmaster Tools to monitor for a couple of weeks post launch to check for 404s and other unexpected issues.

Nodebb to Discourse
Migrating an existing community to Discourse