1
0
mirror of https://github.com/mattermost/focalboard.git synced 2024-12-21 13:38:56 +02:00

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 <wiggin77@warpmail.net>

* Update docs/index.md

Co-authored-by: Doug Lauder <wiggin77@warpmail.net>

* Update index.md

* Update dev-tips.md

Co-authored-by: Doug Lauder <wiggin77@warpmail.net>
Co-authored-by: Justine Geffen <justinegeffen@users.noreply.github.com>
This commit is contained in:
Chen-I Lim 2022-02-08 13:46:14 -08:00 committed by GitHub
parent 761e268bf6
commit ad9e83e8fd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 193 additions and 29 deletions

55
docs/code-review.md Normal file
View File

@ -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.

View File

@ -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.

View File

@ -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).

96
docs/dev-tips.md Normal file
View File

@ -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 <space>` 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! :)

View File

@ -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 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).
Syntax highlighted code block
# Header 1 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.
## Header 2
### Header 3
- Bulleted ## Just ask if you need help!
- List
1. Numbered 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).
2. List
**Bold** and _Italic_ and `Code` text We're glad ❤️ you're here! Good luck and have fun!
[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.

View File

@ -83,7 +83,7 @@ Translated strings are stored in other json files under `webapp/i18n`, e.g. `es.
## Database ## 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 ## Unit tests