diff --git a/docs/GUIDELINES.md b/docs/GUIDELINES.md index 8876b080..549418bc 100644 --- a/docs/GUIDELINES.md +++ b/docs/GUIDELINES.md @@ -2,10 +2,11 @@ ## Communication Channels -* Our source code is [hosted on GitHub](https://github.com/iSoron/uhabits) and this is where all the main development takes place. We use [GitHub Issues](https://github.com/iSoron/uhabits/issues) for keeping track of open bugs and open development tasks. We also have a [gitter channel](https://gitter.im/loophabits/dev) for real-time discussions about coding and pull requests. - +* Our source code is [hosted on GitHub](https://github.com/iSoron/uhabits) and this is where all the main development takes place. We use [GitHub Issues](https://github.com/iSoron/uhabits/issues) for keeping track of open bugs and open development tasks. * Regular users are encouraged to post feature requests and support questions under [GitHub Discussions](https://github.com/iSoron/uhabits/discussions). This is also where major announcements about the project are made. +* There is also a "Technical Discussion" section on GitHub Discussions for general technical issues (e.g., project fails to build). For technical discussions related to the implementation of a particular feature, please open a draft pull request instead. + * Translations are managed in a [separate translation platform](https://translate.loophabits.org/). ## Building and Testing the Project @@ -16,13 +17,13 @@ Please see `docs/BUILD.md` and `docs/TEST.md` This repository uses the [git-flow branching model](https://nvie.com/posts/a-successful-git-branching-model/). Basically, there are two main branches, `dev` and `master`. All the development takes place in the `dev` branch. After the new features have been implemented and tested, they are merged into the `master` branch and a new version of the app is released. Please submit your pull requests against the `dev` branch. -## Submiting Code +## Submitting Code -Proposed code changes should be submitted to the project through [GitHub pull requests](https://github.com/iSoron/uhabits/pulls). For the basic steps of creating a pull request, see [GitHub's documentation](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). The following suggestions will help your pull request gets merged quickly and with few changes. +Proposed code changes should be submitted to the project through [GitHub pull requests](https://github.com/iSoron/uhabits/pulls). For the basic steps of creating a pull request, see [GitHub's documentation](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). The following suggestions will help your pull request get merged quickly and with few changes. -* **Write a clear description of your proposed code changes:** Although it may look obvious to you, it's not always clear to others what is your pull request trying to accomplish. Please always describe what problem is your pull request is trying to solve, and how does it solve it (on a very high level). If you are fixing a bug that has not been reported before, please describe it first, including the steps to reproduce it. +* **Write a clear description of your proposed code changes:** Although it may look obvious to you, it's not always clear to others what your pull request is trying to accomplish. Please always describe what problem your pull request is trying to solve, and how it solves it (on a very high level). If you are fixing a bug that has not been reported before, please describe it first, including the steps to reproduce it. -* If your pull request implements a completely new feature or contains large amounts of code, please **discuss it with other developers before writing it**. You are welcome to ask about it in our developer chat room, or to open a draft pull request outlining how are you planning to solve the problem. The draft pull request may not even contain any code. +* If your pull request implements a completely new feature or contains large amounts of code, please **discuss it with other developers before writing it**. You are welcome to open a draft pull request outlining how you are planning to solve the problem. The draft pull request may not even contain any code. * If your pull request involves changes to the user interface, **please work on a mockup first and submit a draft pull request with your proposed UI changes** before writing the code to make it functional, to gather feedback from other developers and users. [Inkscape](https://inkscape.org/) and [Figma](https://www.figma.com/) are good tools that you can use. @@ -32,6 +33,8 @@ Proposed code changes should be submitted to the project through [GitHub pull re * **Keep refactoring separate.** While implementing bug fixes and new features, you will certainly realize that other parts of our existing code could be improved. Please do not change it yet. Get your bug fix or new feature merged first, then submit a separate pull request for improving the existing code. Avoid renaming classes, removing unnecessary statements, or doing any other refactoring work on pull requests that propose bug fixes or new functionality. +* **AI-assisted pull requests are welcome**, however, since they typically require additional review time to ensure code quality, they should follow the project guidelines even more strictly. In particular, keep them small, and discuss new features with other developers before writing any AI-assisted code. Large (500+ line) AI-assisted pull requests from first-time contributors that implement new features without prior discussion will be closed without consideration. + Further resources: * [*How to Make Your Code Reviewer Fall in Love with You*](https://mtlynch.io/code-review-love), by Michael Lynch.