Skip to content

WIP update the CONTRIBUTING.md guide. #1203

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.

Sign up for GitHub

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

Draft
wants to merge 4 commits into
base: develop
Choose a base branch
from
Draft

WIP update the CONTRIBUTING.md guide. #1203

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8b147dd
WIP update the CONTRIBUTING.md guide.
trusktr Jun 5, 2020
95574e3
Merge branch 'develop' into contributing-guide
anikethsaha Jun 8, 2020
0ad3bb3
Merge branch 'develop' into contributing-guide
sy-records Sep 21, 2020
34df471
Merge branch 'develop' into contributing-guide
jhildenbiddle Oct 9, 2020
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
34 changes: 32 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,39 @@ We welcome any type of contribution, not only code. You can help with

Working on your first Pull Request? You can learn how from this *free* series, [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github).

### Developing

After cloning the project, run the following in your terminal

```sh
npm install
npm run build
npx serve .
Copy link
Member

Choose a reason for hiding this comment

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

Maybe we should mention the dev command before this ?

like after install
npm run dev for streamline one you mentioned below and then this build thing ?

WDYT ?

cause we have the same in gitpod environment as well so for consistency we can have that.

Copy link
Member

Choose a reason for hiding this comment

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

I don't think we should suggest using npx when we have npm scripts setup to accomplish the same thing (in this case, npm run serve). npx requires internet access which means it will fail when working offline, can be slow when internet speeds are slow (rural areas, mobile, developing countries, etc.) and/or expensive when internet charges are high (mobile, bandwidth limits, etc.)

Let's make sure the repo has everything needed for local development.

```

The third command will output a URL like `http://localhost:5000`. Open it in your browser, then you'll see a directory listing. Click on the `docs/` folder and you'll then see the Docsify documentation (built with Docsify of course!) running locally on your computer.
Copy link
Member

Choose a reason for hiding this comment

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

Development server runs on port 3000.

Copy link
Member Author

Choose a reason for hiding this comment

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

  • update port
  • change to npm command

I agree about the change. Sidenote, I think npx falls back to the same as npm and uses the local dependency without the internet when the local dependency is installed.


Any time you change the code, you can re-run `npm run build` to compile the code again, then refresh your browser to see the new changes.

TO make things more streamlined, run

```sh
npm run dev
```

in a separate terminal from where you are running `npx serve .` and it will enter watch mode, so any time you modify the code it will automatically re-build without you having to manually run `npm run build` each time.

As you make changes to the code, also update the test files in the `test/unit/` folder for unit tests. If needed also update the end-to-end integration tests in `cypress/integration/`.

Sometimes the fake DOM APIs that are available in the unit tests (thanks to JSDOM) are enough to test your code, but in other cases you might want to use real DOM APIs in which case you can use the integration testing for this (runs your code in an actual browser environment instead of Node.js). Integration tests are also useful for taking snapshots of the website to ensure that the pixels look as expected.

### Code structure and architecture

### Dev tips

## Submitting code

Any code change should be submitted as a pull request. The description should explain what the code does and give steps to execute it. The pull request should also contain tests.
Once you're happy with your code changes, the changes can be submitted back to the project as a pull request. The pull request description should explain what the changes do. There will be a template to fill out when you create a pull request.

## Code review process

Expand Down Expand Up @@ -64,4 +94,4 @@ Thank you to all our sponsors! (please ask your company to also support this ope
<a href="https://opencollective.com/docsify/sponsor/8/website" target="_blank"><img src="https://opencollective.com/docsify/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/docsify/sponsor/9/website" target="_blank"><img src="https://opencollective.com/docsify/sponsor/9/avatar.svg"></a>

<!-- This `CONTRIBUTING.md` is based on @nayafia's template https://github.com/nayafia/contributing-template -->
<!-- This `CONTRIBUTING.md` is based on @nayafia's template https://github.com/nayafia/contributing-template -->