Contribution Guide

Moved from Mastodon/Hacking -jonny 2023-12-04

Up To: Tech WG, Mastodon/Docs

Good Practices for Collaborative Contributions

• The dev-stable branch is for neuromatch.social's stable custom features only i.e. if a custom feature is extremely relevant to the instance and will likely be maintained indefinitely by the Tech_WG.
  • Choosing to only merge code into dev-stable if it is highly likely to be maintained indefinitely obviates the need to try to untangle feature-specific code later, in the event that we wish to remove it. This would be beneficial in case the author of a custom feature leaves the Tech_WG and no one else on the group has the bandwidth to maintain that feature. This is also useful if the feature no longer meets the needs of the instance.
• The main branch should always be in a state where you can easily roll-back to a previous stable release with our instance's features e.g.custom-glitch4.2 branch. At any given time, the main branch should be the same as one of the custom release branches.
  • If this turns out to be tricky due to past commits to main, then simply deploy the latest stable custom release branch. In this case, we no longer maintain the main branch.
• DO NOT commit even small/important changes directly to main. This makes it hard to keep track of the changes for future merges. If you are fixing a feature from upstream, do it in a separate branch.
• Create a separate branch for each new feature.
  • Keeping feature branches available even after they have been merged into dev-stable makes it easier to recreate the same set of features in the event that the maintenance team decides that dev-stable is in an unmaintainable state.
  • Name feature branches as feature-<insert appropriate name>, e.g. feature-autofollow
  • Keep features as small as possible.
• Choose the parent of the feature branch wisely!
  • If a feature is being added on top of glitch-soc:main, then first sync glitch-clean-sync using the "sync fork" feature on GitHub and then create a feature branch from this synced version. Basing new code directly on the upstream this way leaves you with more flexibility in the event you later decide to get it merged upstream.
  • If a feature is being added on top of some branch feature-XYZ that was added exclusively to neuromatch.social's dev-stable, then:
    • either contribute to the branch feature-XYZ by submitting a PR if your hack enhances the feature.
    • or create a new feature branch by forking glitch-clean-sync if it's a major re-write of the feature-XYZ. If this new feature branch eventually gets merged to dev-stable then the original feature-XYZ branch should be deleted to keep the repo clean.
• Any feature branch must be approved by at least 1 reviewer before it can be merged to dev-stable.
• Features MUST pass tests before they can be merged.
• When a feature has been tested, reviewed, and is ready to be merged, do not merge the feature branch directly to main. Merge to the dev-stable branch
• Clean code -- please be kind to your fellow maintainers who may not know what features you've implemented and save their time by ensuring that that there are no linting errors and no errors in general when you merge a feature branch to the dev-stable branch
• If any authors leave any errors (including linting errors) and proceeds to merge a feature branch with dev-stable, the other maintainers have the right to ignore that feature branch's commits when merging upstream and dev-stable for deploying a new release. In this case, maintainers should inform the author(s) and update the corresponding feature wiki page. If the author(s) be willing to update the feature to resolve merge-conflicts, then follow the process of adding new features mentioned above.

The flowchart illustrates a few principles:

• dev-stable serves as an easy package of all the stable features that can easily be merged into any base branch. It is kept as compact as possible to minimize the likelihood of merge conflicts so that maintainers do not require deep knowledge of the code.
• deployed branches are the product of:
  • the upstream version of glitch (or potentially a different fork in the future)
  • stable features from dev-stable
  • potentially unstable features that are merged separately from feature-* branches
• It is easy to create new branches, and their extensive use makes it easy to roll back to earlier states. If a branch like custom-glitch-4.3.0-unstable turns out to be buggy, admins can git checkout custom-glitch-4.3.0, which should contain all the same code minus the unstable feature.

See Also

• Upgrade Mastodon