Skip to content

Internal contribution guide

Jump to bottom
Andrzej Podobiński edited this page Jan 19, 2022 · 20 revisions

General rules

Here are a couple of points to remember when starting development in Membrane:

  • The task assignee is responsible for watching over it:

    • asking for needed resources/explanation/help
    • keeping it in the proper place in the kanban
    • assigning reviewers and making sure they remember about the review
    • merging pull requests
    • transferring the task to someone else if necessary.

  • When moving a task from "Backlog" to "To do" replace any notes with an issue in the proper repo and assign yourself.

  • Create a branch with a meaningful name

  • You can open a draft PR right away.

  • Remember to link the issue to the PR (either by adding Closes # and PR number or using the UI)

  • Try to avoid making huge PRs - if the feature you're working on is big, create draft PR with a list of steps and ask for a review as early as possible. You can create smaller PRs from sub-task branches and use the main as master for this feature

  • Before requesting review generate docs and check if there are only modules or functions that are part of API there, they have specs and docs, there are no dead links nor out-of-date content etc. It's worth doing even if you didn't change the docs. Do the same when reviewing someone else's PR.

  • When finished, make a self-review before assigning a reviewer.

  • Assign a reviewer. Ask during the stand-up meeting who can do the review. You need at least one approval from one of the core team members and passing CI tests to merge new features.

  • When reviewer requests fixes, refer to each comment in at least one of the following ways:

    • Fix the problem. GitHub usually detects that and automatically marks the comment as 'outdated', but if it doesn't, add a 'done' reply.
    • Start a discussion or ask for an explanation in a reply.
    • If a comment requests new, big features, suggest moving that to a separate PR. Remember to create an issue for that and pin it to the proper column in the kanban.

    Remember to watch for comments accidentally marked as outdated and don't mark someone else's comments as resolved.

  • When you consider all the comments fixed, re-request the review.

  • Do not force push changes to the reviewed commits - this breaks 'changes since last review' functionality on GH

  • Always remove your branch after merging the PR. It should happen automatically. If not, enable that in settings (or ask someone with permissions to do this)

CHANGELOG maintenance

In the membrane_core repository, the CHANGELOG file is maintained. There is a Github action that enforces updating that file on every PR to the master branch. Of course, not all changes require updates in the CHANGELOG, that's why it is possible to mark a PR with a no-changelog label. The label should be added to the PR during creation because unfortunately adding a label later does not re-run the check and it has to be re-run manually. To re-run the check one of the below strategies can be used:

  • git commit --amend --no-edit && git push -f origin <branch> - it can broke the diff shown when the reviewer wants to see "changes since the last review",
  • git commit --allow-empty -m "trigger enforce CHANGELOG action" && git push origin <branch> - it leaves an additional commit in the history.

Creating new plugin/repo

  • Each new plugin should have its own repo and hex package
  • The plugin should contain one or more elements related to the same format/protocol (e.g. H264 plugin may contain decoder, encoder and parser)
  • One plugin should only depend on at most one native library, so if you need separate libraries for decoder and encoder each should be a separate plugin
  • When starting development you should create new repo based on https://github.com/membraneframework/membrane_template_plugin, enable CI and create a branch (often called develop) and follow the usual steps.
  • Place your plugin in the packages list with the [In progress] tag.

Releasing a package

  1. Make sure the repo has proper README with a usage example, docs and no dependencies from Git repositories
  2. [If updating] Bump package version according to Semantic Versioning in mix.exs and README.md
  3. Checkout to master, make sure there are no uncommitted changes (via git status)
  4. Run mix hex.publish. Publish under membraneframework organization (you need an account on hex.pm added to this organization)
  5. Add tag in format v0.0.0 matching package version (git tag v0.0.0)
  6. [IMPORTANT!] Push the tag to the repo (git push --tags)
  7. Create a release on GitHub (go to tags, click the three dots button and then create release). Add some release notes.
  8. Update the repository description and the packages list.

Renaming a package

  1. Checkout to the latest tag e.g. git checkout v0.3.0
  2. Write in README.md that package has been moved like here
  3. Update bugfix version in mix.exs e.g. from 0.3.0 to 0.3.1
  4. Run mix hex.publish. Publish under the membraneframework organization (you need an account on hex.pm added to this organization)
  5. Retire package with mix hex.retire old_package_app version_with_updated_bugifx renamed --message "Renamed to new_package_app"
  6. Don't push these changes to GitHub. Run git checkout -f master
  7. Update minor version of the renamed package and release it according to the Releasing a package section
  8. Rename the GitHub repo
Clone this wiki locally