From ad9e83e8fd008c256aabfaea0e9298c975334361 Mon Sep 17 00:00:00 2001 From: Chen-I Lim <46905241+chenilim@users.noreply.github.com> Date: Tue, 8 Feb 2022 13:46:14 -0800 Subject: [PATCH] Port contributors guide to GitHub pages (#2296) * Port contributor's guide to GitHub * Fix #2178. Port contributors guide to GitHub pages * Fix wrong file change * typo * Fix link * Replace PR with pull request * Remove comment * Doc at-mention, headings * Add sudo apt-get install autoconf dh-autoreconf * database typo * Update docs/dev-tips.md Co-authored-by: Doug Lauder * Update docs/index.md Co-authored-by: Doug Lauder * Update index.md * Update dev-tips.md Co-authored-by: Doug Lauder Co-authored-by: Justine Geffen --- docs/code-review.md | 55 +++++++++++ docs/contribution-checklist.md | 16 ++++ docs/contributions-without-ticket.md | 15 +++ docs/dev-tips.md | 96 +++++++++++++++++++ docs/index.md | 38 ++------ .../contribute/getting-started/dev-tips.md | 2 +- 6 files changed, 193 insertions(+), 29 deletions(-) create mode 100644 docs/code-review.md create mode 100644 docs/contribution-checklist.md create mode 100644 docs/contributions-without-ticket.md create mode 100644 docs/dev-tips.md diff --git a/docs/code-review.md b/docs/code-review.md new file mode 100644 index 000000000..baf55da32 --- /dev/null +++ b/docs/code-review.md @@ -0,0 +1,55 @@ +# Code Review Checklist + +Currently, all changes to the product must be reviewed by a [core committer](/contribute/getting-started/core-committers/#core-committers). + +### If you are a community member seeking a review + +1. Submit your pull request (PR). + * Follow the [contribution checklist](../contribution-checklist/). +2. Wait for a reviewer to be assigned. + * Product managers are on the lookout for new pull requests and usually handle this for you automatically. + * If you have been working alongside a core committer, feel free to message them for help. + * When in doubt, ask for help in the [Focalboard](https://community.mattermost.com/core/channels/focalboard) channel on our community server. + * If you are still stuck, please message Chen Lim (@chenilim on GitHub). +3. [Wait for a review](#if-you-are-awaiting-a-review). + * Expect some interaction with at least one reviewer within 5 business days (weekdays, Monday through Friday, excluding [statutory holidays](https://docs.mattermost.com/process/working-at-mattermost.html#holidays)). + * Keep in mind that core committers are geographically distributed around the world and likely in a different time zone than your own. + * If no interaction has occurred after 5 business days, please [at-mention](https://github.blog/2011-03-23-mention-somebody-they-re-notified/) a reviewer with a comment on your pull request. +4. Make any necessary changes. + * If a reviewer requests changes, your pull request will disappear from their queue of reviews. + * Once you've addressed the concerns, please at-mention the reviewer with a comment on your pull request. +5. Wait for your code to be merged. + * Larger pull requests may require more time to review. + * Once all reviewers have approved your changes, they will handle merging your code. + +### If you are awaiting a review + +1. Wait patiently for reviews to complete. + * Expect some interaction with each of your reviewers within 5 business days. + * There is no need to explicitly mention them on the pull request or to explicitly reach out on our community server. +2. Make any necessary changes. + * If a reviewer requests changes, your pull request will disappear from their queue of reviews. + * Once you've addressed the concerns, assign them as a reviewer again to put your pull request back in their queue. + +### If you are a core committer asked to give a review + +1. Respond promptly to requested reviews. + * Assume the requested review is urgent and blocking unless explicitly stated otherwise. + * Try to interact with the author within 2 business days. + * Configure the GitHub plugin to automate notifications. + * Review your outstanding requested reviews daily to avoid blocking authors. + * Prioritize earlier milestones when reviewing to help with the release process. + * Responding quickly doesn't necessarily mean reviewing quickly! Just don't leave the author hanging. +2. Feel free to clarify expectations with the author. + * If the code is experimental, they may need only a cursory glance and thumbs up to proceed with productizing their changes. + * If the review is large or complex, additional time may be required to complete your review. Be upfront with the author. + * If you are not comfortable reviewing the code, avoid "rubber stamping" the review. Be honest with the author and ask them to consider another core committer. +3. Never rush a review. + * Take the time necessary to review the code thoroughly. + * Don't be afraid to ask for changes repeatedly until all concerns are addressed. + * Feel free to challenge assumptions and timelines. Rushing a change into a patch release may cause more harm than good. +4. Avoid leaving a review hanging. + * Try to accept or reject the review instead of just leaving comments. +5. Merge the pull request. + * Do not merge if there are outstanding changes requested. + * Merge the pull request, and delete the branch if not from a fork. diff --git a/docs/contribution-checklist.md b/docs/contribution-checklist.md new file mode 100644 index 000000000..9e85e1370 --- /dev/null +++ b/docs/contribution-checklist.md @@ -0,0 +1,16 @@ +# Contribution Checklist + +Thanks for your interest in contributing code! + +Follow this checklist for submitting a pull request (PR): + +1. You've signed the [Contributor License Agreement](http://www.mattermost.org/mattermost-contributor-agreement/), so you can be added to the Mattermost [Approved Contributor List](https://docs.google.com/spreadsheets/d/1NTCeG-iL_VS9bFqtmHSfwETo5f-8MQ7oMDE5IUYJi_Y/pubhtml?gid=0&single=true). +2. Your ticket is a Help Wanted GitHub issue for the project you're contributing to. + - If not, follow the process [here](contributions-without-ticket). +3. Your code is thoroughly tested, including appropriate unit tests, and manual testing. +4. If applicable, user interface strings are included in the localization file ([en.json](https://github.com/mattermost/focalboard/blob/main/webapp/i18n/en.json)) + - In the webapp folder, run `npm run i18n-extract` to generate the new/updated strings. +5. The PR is submitted against the `main` branch from your fork. +6. The PR title begins with the GitHub Ticket ID (e.g. `[GH-394]`) and the summary template is filled out. + +Once submitted, the automated build process must pass in order for the PR to be accepted. Any errors or failures need to be addressed in order for the PR to be accepted. Next, the PR goes through [code review](code-review). To learn about the review process for each project, read the [CONTRIBUTING.md](https://github.com/mattermost/focalboard/blob/main/CONTRIBUTING.md) file of that GitHub repository. diff --git a/docs/contributions-without-ticket.md b/docs/contributions-without-ticket.md new file mode 100644 index 000000000..e61282b5c --- /dev/null +++ b/docs/contributions-without-ticket.md @@ -0,0 +1,15 @@ +# Contributions Without Ticket + +Contributions for minor corrections and improvements without a corresponding `Help Wanted` ticket are welcome. For example, a pull request for a bug or incremental improvement, with less than 20 lines of code change, is usually accepted if the change to existing behaviour is minor. + +All pull requests submitted without a corresponding ticket will first be reviewed by a core team product manager. Some examples of minor corrections and improvements include: + +- [Fix a formatting error in help text](https://github.com/mattermost/mattermost-server/pull/5640) +- [Fix success typo in Makefile](https://github.com/mattermost/mattermost-server/pull/5809) +- [Fix broken Cancel button in Edit Webhooks screen](https://github.com/mattermost/mattermost-server/pull/5612) +- [Fix Android app crashing when saving user notification settings](https://github.com/mattermost/mattermost-mobile/pull/364) +- [Fix recent mentions search not working](https://github.com/mattermost/mattermost-server/pull/5878) + +**Note:** For pull requests greater than 20 lines of code, a `Help Wanted` ticket should be opened by the core team. This helps ensure that everything going into the project aligns with a unified vision. Core committers who review the PR are entitled to reject it if there isn't a `Help Wanted` ticket and feel it significantly changes behavior or user expectations. + +The best way to discuss opening a `Help Wanted` ticket with the core team is by [starting a conversation in Contributors channel](https://community.mattermost.com/core/channels/focalboard) or [opening an issue in the GitHub repository](https://github.com/mattermost/focalboard/issues/new). diff --git a/docs/dev-tips.md b/docs/dev-tips.md new file mode 100644 index 000000000..d32d79a6f --- /dev/null +++ b/docs/dev-tips.md @@ -0,0 +1,96 @@ +# Developer Tips and Tricks + +## Installation prerequisites + +Check that you have recent versions of the basic dependencies installed: +* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + * On Windows, install [Git for Windows](https://gitforwindows.org/) and use the git-bash terminal shell +* [Go](https://golang.org/doc/install) +* [Node](https://nodejs.org/en/download/) (v10+) and [npm](https://www.npmjs.com/get-npm) + +On Windows: +* Install [Mingw64](https://chocolatey.org/packages/mingw) via [Chocolatey](https://chocolatey.org/) + +On macOS, to build the Mac app: +* Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) (v12+) +* Install the Xcode commandline tools, via the IDE or run `xcode-select --install` + +On Linux, to build the Linux app: +* `sudo apt-get install libgtk-3-dev` +* `sudo apt-get install libwebkit2gtk-4.0-dev` +* `sudo apt-get install autoconf dh-autoreconf` + +## Clone the project source code + +Clone the [GitHub repo here](https://github.com/mattermost/focalboard). + +## Build and run from the terminal + +Follow the steps in the [main readme file](https://github.com/mattermost/focalboard#building-the-server). In summary, to build and run the server: + +``` +make prebuild +make + ./bin/focalboard-server +``` + +Then open a browser to `http://localhost:8000` to access it. The port is configured in `config.json`. + +Once the server is running, you can rebuild just the webapp with `make webapp` (in a separate terminal window), then reload the browser. + +## VSCode setup + +Here's a recommended dev-test loop using VSCode: +* Open a bash terminal window to the project folder +* Run `make prebuild` to npm install + * Do this again when dependencies change in `webapp/package.json` +* Run `cd webapp && npm run watchdev` + * This will auto-build the webapp on file changes +* Open VSCode + * Install the [Go](https://marketplace.visualstudio.com/items?itemName=golang.Go) and [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) VSCode extensions if you haven't already +* Hit F5 and select `Go: Launch Server` + * Or, press `Cmd+P` and type `debug ` and pick the option +* Open a browser to `http://localhost:8000` + * The port is configured in `config.json` + +You can now edit the webapp code and refresh the browser to see your changes. + +## Debugging the web app + +You can use your favorite browser to debug the webapp code. With Chrome, open the dev tools with `Cmd+Alt+I` (`Ctrl+Alt+I` in Windows). +* `npm run watchdev` builds the dev package, which includes source maps from js to typescript +* In the Chrome devtools source tab, press `Cmd+P` to jump to a source file + +As a starting point, add a breakpoint to the `render()` function in `BoardPage.tsx`, then refresh the browser to walk through page rendering. + +## Debugging the server + +Debug the Go code in VSCode. This is set up automatically when you launch the server from there. + +To start, add a breakpoint to `handleGetBlocks()` in `server/api/api.go`, then refresh the browser to see how data is retrieved. + +## Localization/Internationalization/Translation + +We use `i18n` to localize the web app. Localized string generally use `intl.formatMessage`. When adding or modifying localized strings, run `npm run i18n-extract` in `webapp` to rebuild `webapp/i18n/en.json`. + +Translated strings are stored in other json files under `webapp/i18n`, e.g. `es.json` for Spanish. + +## Database + +By default, data is stored in a sqlite database `focalboard.db`. You can view and edit this directly using `sqlite3 focalboard.db` from bash. + +## Unit tests + +Before checking-in commits, run: `make ci`, which is simlar to the ci.yml workflow and includes: +* Server unit tests: `make server-test` +* Webapp eslint: `cd webapp; npm run check` +* Webapp unit tests: `make webapp-test` +* Webapp UI tests: `cd webapp; npm run cypress:ci` + +## Running into problems or have questions? + +If you run into any issues with the steps here, or have any general questions, please don't hesitate to reach out either on [GitHub](https://github.com/mattermost/focalboard) or our [Mattermost community channel](https://community.mattermost.com/core/channels/focalboard). + +We welcome everyone, and appreciate any feedback. + +glhf! :) diff --git a/docs/index.md b/docs/index.md index 01c76ac6e..9975f9d57 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,37 +1,19 @@ -## Welcome to GitHub Pages +# Focalboard/Mattermost Boards Contributors Guide -You can use the [editor on GitHub](https://github.com/mattermost/focalboard/edit/main/docs/index.md) to maintain and preview the content for your website in Markdown files. +Welcome to the Focalboard/Mattermost Boards project! -Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files. +We're very glad you want to check it out and perhaps contribute code our repository in GitHub. -### Markdown +Our goal is to make your experience as great as possible. Follow these simple steps to contribute: -Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for +1. [Clone the project from GitHub](https://github.com/mattermost/focalboard) and follow the steps in the README to build. Read the [developer tips & tricks](dev-tips) to get started. -```markdown -Syntax highlighted code block +2. Find [help wanted tickets in GitHub](https://github.com/mattermost/focalboard/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). Comment to let everyone know you’re working on it, and to allow a core contributor to assign the issue to you. If there’s no ticket for what you want to work on see [contributions without a ticket.](contributions-without-ticket). -# Header 1 -## Header 2 -### Header 3 +3. When your changes are ready, run through our [checklist for pull requests](contribution-checklist). Note that if it’s your first contribution, there is a standard [CLA](https://www.mattermost.org/mattermost-contributor-agreement/) to sign. -- Bulleted -- List +## Just ask if you need help! -1. Numbered -2. List +You can find us on our [public Focalboard channel](https://community.mattermost.com/core/channels/focalboard) on the Mattermost community server. Also feel free to [file a bug](https://github.com/mattermost/focalboard/issues/new/choose) for any issues you run into, or [start a discussion](https://github.com/mattermost/focalboard/discussions). -**Bold** and _Italic_ and `Code` text - -[Link](url) and ![Image](src) -``` - -For more details see [Basic writing and formatting syntax](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). - -### Jekyll Themes - -Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/mattermost/focalboard/settings/pages). The name of this theme is saved in the Jekyll `_config.yml` configuration file. - -### Support or Contact - -Having trouble with Pages? Check out our [documentation](https://docs.github.com/categories/github-pages-basics/) or [contact support](https://support.github.com/contact) and we’ll help you sort it out. +We're glad ❤️ you're here! Good luck and have fun! diff --git a/website/site/content/contribute/getting-started/dev-tips.md b/website/site/content/contribute/getting-started/dev-tips.md index cd4038f52..5df65626c 100644 --- a/website/site/content/contribute/getting-started/dev-tips.md +++ b/website/site/content/contribute/getting-started/dev-tips.md @@ -83,7 +83,7 @@ Translated strings are stored in other json files under `webapp/i18n`, e.g. `es. ## Database -By default, data is stored in a sqlite datebase `focalboard.db`. You can view and edit this directly using `sqlite3 focalboard.db` from bash. +By default, data is stored in a sqlite database `focalboard.db`. You can view and edit this directly using `sqlite3 focalboard.db` from bash. ## Unit tests