Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add contributing guidelines #148

Closed
wants to merge 8 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
## Communication

We use [slack](https://goldcardcommunity.slack.com/) for talking about all `#website` matters.
Copy link
Collaborator

@erickhun erickhun Sep 29, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we list that one, we should be aware that this will be public.

Will guest be allowed to that channel? Someone at g0v just asked me where things get coordinated. I think having "guests" to that channel might be great?

The chat might be better for quick feedbacks loop than github issues, and keep the interest of outsider contributors

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By default they need an invite until we let them in if I'm not wrong.

I like the guest model, it could be a good taste of what it's like to be in the gold card community.


## Content Editors

Please join the slack channel above. We will give you access to a CMS to edit content / create new posts.

The [flow](https://github.com/taiwangoldcard/website/issues/46#issuecomment-695207432) is like this:

1. Create / Edit content on the CMS
2. Save
3. CMS will automatically help you request for approval. See this [example](https://github.com/taiwangoldcard/website/pull/139)
4. Someone will approve and publish your changes
5. See your new content live on https://taiwangoldcard.com

Alternatively, if you are already comfortable with git, then you can go to [`content` ](https://github.com/taiwangoldcard/website/tree/master/content) folder and edit the pages. Afterwards, raise a Pull Request (see below).

## Developers

1. Feel free to contribute code by raising a [Pull Request](https://github.com/taiwangoldcard/website/pulls). Keep your code change as light as possible, with [atomic commits](https://coderwall.com/p/jmqp0a/why-and-how-i-craft-atomic-commits-in-git) so the whole thing is easier to review.

2. Alternatively, use the [issues](https://github.com/taiwangoldcard/website/issues) page to raise ideas / suggestions.

### Code structure

- Content: `content/` -- Most copy should be edited here.
- HTML: `themes/compose/layout/` -- is where you want to modify the layout
- JS: `themes/compose/assets/js/` -- is where you want to modify or add new JS functionality
- CSS: `themes/compose/assets/sass/` -- is where is the styles are. `hugo` will automatically translates it to CSS

- Output: `docs/` is the "build" folder, where GitHub look at to show the [Taiwan Gold Card](https://taiwangoldcard.com/) website

### Tests

We have frontend tests (with cypress) to check if the website still works properly before being available on the website. All tests are ran automatically via [github workflows](./workflows/tests.yml) when you push a commit. You can see them [here](https://dashboard.cypress.io/projects/rtyzr7/runs). Each test has a video attached to it.

If you need to run the tests locally:

1. First, install node / npm. This is required for the test executable. You may use [Node Version Manager](https://github.com/nvm-sh/nvm):

```
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
```

2. At this repo's root, perform `npm install`. This will install `cypress`, the automated test runner.

3. Run the application `npm start`.

4. Run the tests `npm test`.

5. (Optional) To debug tests, you can `./node_modules/cypress/bin/cypress open` to view the interactive UI and select the tests to run:

![Cypress Tests UI](../tests-ui.png)

### Deploy changes

When you push to master (or merge a Pull Request), a [github action workflow](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions) will be automatically called, and deploy your changes to the website.

You can see how it works in the [deploy workflow](./workflows/deploy.yml)