matterhorn-40400.0.0: PRACTICES.md
Matterhorn Project Practices ============================ This document captures some important project practices that we employ. If you want to contribute to Matterhorn, for best results, please follow these practices. Many of the practices described below are really about serving some overall concerns: * We want to provide a working program to people who want to use it, * We want to manage inevitable software evolution, and * We want to reduce waste through good team coordination. Branching --------- * The `master` branch should be stable enough to be release-ready at all times. This promise helps us be agile in the event of a need to do an unplanned release. * The `develop` branch is where development occurs. * New feature development begins and stays on a new feature branch, typically named `feature/FEATURENAME`, until it is declared stable enough to be merged. Once more testing of a feature is needed, especially in concert with other work, it should be merged to `develop`. * Once `develop` has been deemed stable enough to release, it can be merged to `master`. * When a feature branch implementation is complete, before merging to `develop` we do a code review that is appropriate to the level of complexity and risk of the work being merged, which may involve an in-person code tour but typically involves just commit review with questions and requests for changes. We do this to ensure that other team members are aware of the ramifications of the work, to provide an opportunity for feedback, and to get fresh eyes on the work to spot problems that won't be evident to its author. * Bug fixes and other small, uncontroversial changes can be committed directly to `master` and merged back into `develop`. This ensures that bug fixes are not held up by other development work in case a bugfix release is desired. Issue Tracking -------------- * We use the GitHub issue tracker for user bug reports and feature requests, and to capture our own intentions about planned and potential work. * We use milestones to group tickets for big efforts, such as server compatibility releases or planning cycles. * When creating issues, we try to make issues as actionable as possible when the scope and details are well-understood, but this isn't always possible. If we can't be concrete about what a ticket entails, we assign the label `high-level` to indicate that more team discussion or context-gathering will be required before a concrete plan can be made. We also use the label `high-level` to indicate any ticket with insufficient detail that needs further discussion before we can tackle it. Workflow -------- * When planning big efforts, we strive to get team alignment on the scope of planned efforts. Creation of a ticket does not necessarily mean that we have gotten team alignment or settled on scope. The appropriate scope will be a function of time and availability, pragmatism, feature parity with upstream, motivation, etc. * When doing refactoring that may be risky or touch a lot of the program, we strive to break the job down into a sequence of incremental changes that each produce a working program and ultimately get us where we want to be. * When planning new work, we strive to get input from the team before the work begins, rather than after it is completed, to reduce waste and to ensure that the work is well-informed. The bigger or more impactful the change, the more important this is - and it applies to work done in spare time as well as at work. * If resources allow, consider pair programming as a means of tackling bigger, cross-cutting problems. Although it costs more in terms of person-hours, it can be a very effective technique for producing better designs with fewer bugs and more mind-sharing. * For experimental work or new features, consider "prototyping" or "throwaway coding," in which the first implementation of a new feature is *intended* to be discarded upon completion. Rather than producing code, the result of this is the learning that occurs when exploring a design. Then, having learned, one can embark on a better-informed implementation. Design ------ We would like issues not to linger too long unaddressed, because then the meaning of "open ticket" is ambiguous to us and to end users: is it planned? Is it well-understood? It's unclear. But we can only tackle so many things, and sometimes we don't even know enough about what's involved in a task to know its level of effort. So in the mean time, before we can investigate, the ticket lingers. Once we're learning what is inovlved, using the ticket as a place to hash out ideas or collect context is annoying because using ticket comments for that isn't effective. To address these concerns: * Whenever we have some high-level thing we want to implement, instead of creating a placeholder ticket, make a page on the project wiki at https://github.com/matterhorn-chat/matterhorn/wiki On this page we'll collaboratively hash out design ideas, collect context and research, and share approaches. These documents represent a "staging ground" for new ideas. * Once enough context has been gathered to support moving forward on the feature, create concrete tickets from the context. It's also possible we decide *not* to move forward, in which case the rationale for aborting can be clearly captured on the wiki. This way, external users can see why we decided not to implement something. * When external users create tickets for high-level features that cannot be implemented immediately but that we agree deserve consideration and need further investigation, close the tickets by referring to the newly-created context wiki page where we'll be hashing out the details. This means that we strive to ensure that open tickets are by definition always workable and fleshed-out. * This way, when external users stop by to ask about features, we can point them at those pages to make it easier to 1) share the developed context, 2) make it clear what is missing in case they want to help, and 3) keep a record of design decisions for posterity even after the feature is implemented.