The Tutor Maintainer Handbook

Community Maintainers
1

The Tutor Maintainers Program was created following the realisation that Tutor was becoming a cornerstone of the Open edX ecosystem: with more and more users depending on Tutor to run their Open edX platforms, it became important to provide these users with a clear and transparent process to contribute to the project and help guide the roadmap.

Historically, the Tutor project has been mostly developed and maintained by a single person (@regis). Now that the project has reached a more stable state, it makes sense to rely more on the community that aggregated around Tutor and Open edX to support existing features, develop new ones and assist other users. To this end, Tutor users are invited to join the Maintainers Program.

Roles and responsibilities

All maintainers are expected to:

  • Behave respectfully and in a professional manner in all their interactions with the community.
  • Help others to the best of your knowledge.
  • Strive to respond shortly and make sure that no message remains unanswered for too long – within their capacity.
  • Have no fear of admitting their ignorance.

In order to follow the news about the maintainers program, maintainers are expected to set the notification level to (at least) “Watching First Post” of the Maintainers and Tutor Enhancement Proposals (TEPs) categories.

Tutor maintainers are granted one or more of the following roles, which they get to choose in their application.

@moderators

This forum needs moderators to remain a great place for people to talk about Tutor and Open edX. The responsibilities of moderators include, but are not limited to:

  • Editing topics for formatting and typos.
  • Editing wikis to keep them up-to-date.
  • Assigning topics to the right category.
  • Bringing other maintainers to the conversation.
  • Making sure that everyone is behaving properly.

This is the only role that does not require expertise about Tutor or Open edX. However, familiarity with Tutor/Open edX is recommended to understand what the conversations are actually about.

Moderators are not expected to read all posts from all topics in every category, but they should do their best to keep a tab on most conversations. Thus, moderators should probably set their notification level to “Watching First Post” for the entire forum.

The first post of every topic should be well written and edited to encourage answers. For instance:

  • Edit the topic title and first post to get rid of obvious typos and spelling mistake.
  • Replace incorrectly used quotes by preformatted text. For instance, when pasting logs, don’t write:

Traceback (most recent call last):
File “./manage.py”, line 123, in
execute_from_command_line([sys.argv[0]] + django_args)
File “/openedx/venv/lib/python3.8/site-packages/django/core/management/init.py”, line 381, in execute_from_command_line
utility.execute()

but write instead:

Traceback (most recent call last):
  File "./manage.py", line 123, in <module>
    execute_from_command_line([sys.argv[0]] + django_args)
  File "/openedx/venv/lib/python3.8/site-packages/django/core/management/__init__.py", line 381, in execute_from_command_line
    utility.execute()
  • If necessary, send private messages to explain how to format text in posts.
  • When posts are insufficiently detailed, encourage people to provide more information.
  • Suggest to replace screenshots by preformatted text, to make it easier for people with the same problem to find the answer.
  • Find unanswered topics and try to bring more people to the conversation.

@experts

Experts are technically-minded people who have acquired an expertise with the use and development of Tutor and Open edX. Their role is to help answer technical questions from other users. Experts are expected to know how to install, use and troubleshoot Open edX platforms. In many (though not all) cases, being able to read and write Python code will be necessary to investigate issues.

Experts are expected to set their notification level to at least “Watching First Post” on the Tutor and Open edX categories.

Experts should do their best to understand what is causing the issue, and how to fix it, now and in the future. Quite often, fixing an issue for future users means adding more information to the docs. Don’t hesitate to ask for help from @developers. When giving an answer, explain why it resolves the problem.

Experts are not a hotline: they are volunteers and they are not here to provide customer service. It’s perfectly OK not to answer a topic for a few hours or days. As a rule of thumb, users should expect answers within three business days, but this is in no way guaranteed. In particular, experts are not required to provide advice on how to customize an Open edX platform – especially to professional developers who usually get paid to implement such customizations. For professional support, users should go to the #marketplace.

@developers

Developers are people who are specifically tasked with reviewing pull requests and issues on the Tutor repositories. Developers are also tasked with fixing bugs and developing new features.

Developers will be added to the tutor-developers team on Github. They should click the “watch” button on all repositories that they would like to contribute. In addition, they should also “follow” the overhangio organization.

When reviewing a PR, make sure that:

  • Code works as intended, is readable and properly documented (in this order).

  • User-facing changes made to the tutor are listed in the Changelog.

  • Tests pass successfuly: on the tutor repo this is achieved by running make test. Most other repos don’t have tests. There is currently no CI in place for PRs, so we will have to create one (with Github Actions).

  • Code is properly formatted with black.

  • Git messages are informative and well written:

    • Use conventional commit titles
    • In the title, describe why we are making this change, not what change is being made. For instance, write:

    fix: “TypeError” when running “tutor local start”

    and not:

    fix: catch exceptions in “docker_compose” method

    • Write commit messages below commit titles. 90-95% of commits should include a detailed, extensive commit message. Describe the technical choices you made (“what”) and how they solve the issues (“why”).
    • Link to relevant conversations from the forums.

Privileges

In exchange for their contributions, Tutor maintainers are invited to help reach decisions on Tutor Enhancement Proposals (TEPs).

How to become a maintainer

We want to very strongly encourage participation in the program, and the barrier to entry is thus very low. Basically, if you decide to apply then we trust that you know what you are doing. Are you interested in joining the program? That’s great! Here are the steps:

  1. Add information to your profile, such that we know who you are. Include your full name, company and add an avatar. Anonymous applications are not accepted. (For reference, here is @regis’ profile)
  2. Review the roles above and decide to which group(s) you would like to be assigned (moderator, expert, developer).
  3. Hit the “Request” button in the maintainers group: :arrow_right: @maintainers :arrow_left: In your message, list the roles you are applying to, describe your experience with Tutor/Open edX, and explain what you aim to achieve as a maintainer. If you are applying as a developer, add your Github handle to your application.
  4. Wait for a reply.
  5. Once you have been granted access, add yourself to the list of maintainers.
  6. Write a post in the Maintainers category to say hi. Welcome to the gang! :hugs:

How to take time off as a maintainer

Don’t burn out! You are encouraged to take time off whenever you want. Just set yourself as OFF in the maintainers list.

A personal note

I would like to say that the creation of this program is an exciting turn in the life of Tutor, which is a personal project that I very much cherish. I am eager to bring more people on board and I can’t wait to see the things that we will achieve together :hugs:

5 Likes