MoodleNet/Contributing

Jump to: navigation, search

<< Back to MoodleNet index


Contribution guidelines

How we collaborate

First off, thank you for considering contributing to MoodleNet!

Our aim is for this project to make you feel welcome as a contributor. We hugely value the comments and contributions of community members in the various publicly-accessible areas in use, which currently are:

Other useful information

  • It’s early days for MoodleNet, so we’re focused on laying down the foundations for the project. This means that you won’t find much usable code yet.
  • We’re working as openly and transparently as possible with this project. As a contributor or member of the MoodleNet community, almost everything you come across will link to some other things that you should have access to. If you don’t have access, and you think you should, just ask!
  • We're planning to resurrect our monthly community calls in 2019, which you’ll find announced on our blog.

We practice Ethical Design

We endeavour to build technology that respects human rights, human effort, and human experience, and hope you will join in this effort.

Ethical Design diagram

Find out more about ethical design at: https://2017.ind.ie/ethical-design

How Can I Contribute?

Submitting Feature Requests, Enhancement Suggestions or Bug Reports

This section guides you through submitting a ✨ feature request, 💄 enhancement suggestions, and 🐛 bug reports for MoodleNet - anything from errors and crashes, to minor improvements, to completely new features.

When you post an issue, please include as many details as possible. Fill in the issue template (available below) to help us resolve issues faster.

All issue tickets should be “bite-sized”, and definitely no more than a sprint’s worth of coding work (currently we do 2 week sprints). Larger tasks/projects are represented as Epics.

Before making a submission

Please go through the checklist below before posting any ✨ 💄 🐛

  • Check if you’re using the latest version of MoodleNet and all its relevant components and if you can get the desired behaviour by changing some config settings.
  • Check if there’s already a community extension or app which provides that enhancement.
  • Perform a cursory search in the feature/improvement list and issue tracker to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
  • Never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to moodlenet-moderators@moodle.com.

Note: If you find a Closed issue that seems like it is the same thing that you’re experiencing, open a new issue and include a link to the original issue in the body of your new one.


Suggesting Features & Enhancements

If you find yourself wishing for a feature that doesn’t exist in MoodleNet, you are probably not alone. There are probably others out there with similar needs. Make a post on ChangeMap which describes the feature you would like to see, why you need it, and how it might work.

Open an issue providing the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a description of the suggested enhancement in as many details as possible, including the steps that you imagine you (as a user) would take if the feature you’re requesting existed.
  • Describe the current behaviour and explain which behaviour you would like to see instead and why.
  • Include screenshots and animated GIFs which help you demonstrate the steps or point out the parts of MoodleNet which the suggestion is related to. You can use a tool called LICEcap to record GIFs on macOS and Windows, and Silentcast or Byzanz on Linux.
  • Provide specific examples to demonstrate the enhancements. If possible, include drawings, screenshots, or gifs of similar features in another app.
  • Explain why this enhancement would be useful to most participants of MoodleNet and isn’t something that can or should be implemented as a community extension.
  • List some other communities, platforms or apps where this enhancement exists.

Reporting Bugs 🐛

Open an issue providing the following information by filling in issue template below, explaining the problem and including additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as many details as possible. For example, start by explaining where you started in MoodleNet, and then which actions you took. When listing steps, don’t just say what you did, but explain how you did it. For example, if you moved the cursor to the end of a line, explain if you used the mouse or a keyboard shortcut, and if so which one?
  • Provide specific examples to demonstrate the steps. Include links to files, screenshots, or copy/pasteable snippets, which you use in those examples. If you’re providing snippets in the issue, use Markdown code blocks.
  • Describe the behaviour you observed after following the steps and point out what exactly is the problem with that behaviour.
  • Explain which behaviour you expected to see instead and why.
  • Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
  • If you’re reporting a crash, include a crash report with error logs.
  • If the problem wasn’t triggered by a specific action, describe what you were doing before the problem happened and share more information using the guidelines below.

Provide more context by answering these questions:

  • Did the problem start happening recently (e.g. after updating to a new version) or was this always a problem?
  • If the problem started happening recently, can you reproduce the problem in an older version? What’s the most recent version in which the problem doesn’t happen?
  • Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
  • If the problem is related to a user or item (eg. collection or resource), does the problem happen for all of them or only some? Does the problem happen only when working with local (originating from your MoodleNet instance) or remote ones, with items of a specific type (e.g. only PDFs)? Is there anything else special about the users or items in question?

Include details about your configuration and environment:

  • Which version of each component are you using?
  • What’s the name and version of the OS you’re using?
  • Are you running in a virtual machine? If so, which VM software are you using and which operating systems and versions are used for the host and the guest?

Template for submitting issues

Description

[Description of the issue]

Steps to Reproduce

  1. [First Step]
  2. [Second Step]
  3. [and so on…]

Expected behaviour:

[What you expect to happen]

Actual behaviour:

[What actually happens]

Reproduces how often:

[What percentage of the time does it reproduce?]

Versions

[What MoodleNet instance you’re using, and the versions of each relevant app or component, including your OS and browser.]

Additional Information

[Any additional information, configuration or data that might be necessary to reproduce the issue.]


Contributing

A common misconception about contributing to free and open source projects is that you need to contribute code. In fact, it’s often the other parts of a project that are most overlooked. You’ll do the project a huge favour by offering to pitch in with these types of contributions!

Even if you like to write code, other types of contributions are a great way to get involved with a project and meet other community members. Building those relationships may open up unexpected opportunities.

Do you like to design? 🎨

  • Restructure layouts to improve the project's usability
  • Conduct user research to reorganise and refine the project's navigation or menus
  • Create art for icons and app screens

Do you like to write? 🖉

  • Write and improve the project's documentation
  • Write tutorials for the project
  • Curate a wiki page of examples showing how the project can be used

Do you like organising? 📥

  • Link to duplicate issues, and suggest new issue labels, to keep things organised
  • Go through open issues and suggest revisiting or closing old ones
  • Ask clarifying questions on recently opened issues to move the discussion forward

Do you like helping people? 🙋‍♀️

  • Answer questions about the project on forums and other sites
  • Answer questions for people on open issues

Do you like helping others code? 👐

  • Review code on other people’s submissions
  • Write tutorials for how a project can be used
  • Offer to mentor another contributor

Do you like to code? 🔩

  • Find an open issue to tackle
  • Offer to help write a new feature
  • Improve tooling, testing & deployment options
  • Read the **next section for guidelines**

---

Contributing Code

Unsure where to begin contributing? You can start by looking through issues tagged with:

  • first-timers-only
    - issues which should only require a few lines of code, and a test or two.
  • help-wanted
    - issues which should be a bit more involved than
    first-timers-only
    issues.

Modularity

MoodleNet is a large project that is intentionally very modular — it will be made up of many components in many repositories. When you initially consider contributing, you might be unsure about which of those repositories should implement the functionality you want to add or improve - the project maintainers can help with that.

Local development

MoodleNet and all packages can be developed locally. For instructions on how to do this, please see the documentation (TBD).

Coding & git practices

  • We use GitLab’s merge requests as our code review tool
  • We encourage any dev to comment on merge requests and we think of the merge request not as a “please approve my code” but as a space for co-developing.
  • We develop features on separate branches identified by issue numbers.
  • We use merge to
    develop
    (not rebase) so that commits related to an issue can be retroactively explored.
  • We don’t currently use release branches or tags because we don’t have release management at this phase of development.

How to make changes

  • Make your changes on a seperate branch which includes an issue number e.g.
    1234-some-new-feature
    where 1234 is the issue number where the feature is documented. Make sure the branch is based on
    develop
    .
  • Do not commit changes to files that are irrelevant to your feature or bugfix.
  • Use commit messages descriptive of your changes.
  • Push to the upstream of your new branch.
  • Create a merge request at GitLab.

Git commit messages

  • Limit the first line to 72 characters or less, referencing relevant issue numbers
  • Be as descriptive as you want after the first line
  • Consider starting the commit message with an applicable emoji (see Issue & Commit Categories below)

Merge requests

  • Follow the code styleguides (TBD).
  • Document new code based on the documentation styleguide (TBD)
  • Each merge request should implement ONE feature or bugfix. If you want to add or fix more than one thing, submit more than one merge request.
  • Fill in the merge request template below
  • Include relevant issue number(s) in the merge request title
  • Include screenshots or animated GIFs in your merge request whenever possible.
  • End all files with a newline

Template for merge requests

  • Description of the change
  • Applicable issue numbers
  • Alternate designs/implementations
  • Benefits of this implementation
  • Possible drawbacks
  • Why should this be part of a core component?
  • Testing process

Issue & Commit Categories

  • 🚑 `critical` : Critical hotfix!
  • 💄 `enhancement` : General improvements.
  • ✨ `feature` : New features.
  • 🐛 `bug` : Confirmed bugs, or reports that are likely to be bugs.
  • 🙋‍♀️ `question` : Questions (e.g. how can I do X?)
  • 📮 `feedback` : General feedback.
  • 🎨 `ui` : Visual design.
  • 📜 `copy` : Text in the apps, or translations.
  • ℹ️ `documentation` : Documentation.
  • 🏇 `performance` : Performance.
  • 🔒 `security` : Security.
  • 🔌 `api` : MoodleNet's APIs.
  • 👽 `external` : External libraries or API integrations.
  • ⚠️ `exception` : Uncaught exceptions.
  • 🔥 `crash` : Crash.
  • 🔣 `encoding` : Character encoding or data serialization issue.
  • 🚚 `cleanup` : Removing, moving or refactoring code or files.
  • ✅ `tests` : Testing

Issue Status

  • 💬 `discussion` : Discussion to clarify this issue is ongoing.
  • 🔜 `todo` : This has been discussed and now needs work.
  • 🔁 `needs-more-info` : More information needs to be collected about these problems or feature requests (e.g. steps to reproduce).
  • 💡 `idea` : Needs to be discussed further. Could be a feature request which might be good to first implement as a community extension.
  • 🚧 `in-progress` : Someone is working on this...
  • 🙏 `help-wanted` : The MoodleNet core team would appreciate help from the community in resolving these issues.
  • 🌱 `first-timers-only` : Less complex issues which would be good first issues to work on for users who want to contribute.
  • 🔢 `needs-reproduction` : Likely bugs, but haven't been reliably reproduced.
  • 🔴 `blocked` : Blocked on other issues.
  • 2️⃣ `duplicate` : Duplicate of another issue, i.e. has been reported before.
  • 🙅 `wontfix` : The MoodleNet core team has decided not to fix these issues (or add these features) for now, because they're working as intended, or some other reason.
  • 🚮 `invalid` : Issues which are not valid (e.g. spam or submitted by error).

Merge Request Status

  • 🚧 `in-progress` : Still being worked on, more changes will follow.
  • 🚏 `needs-review` : Needs code review and approval from maintainers.
  • 🔍 `under-review` : Being reviewed by maintainers.
  • 🔧 `changes-required` : Needs to be updated based on review comments and then reviewed again.
  • 👀 `needs-testing` : Needs manual testing.

---

Credits

The following documents have greatly helped us put this together. A big thank you to their authors and contributors!