Skip to content

Commit

Permalink
Fix ln -s command in CONTRIBUTING.md #trivial (#660)
Browse files Browse the repository at this point in the history
  • Loading branch information
pmcelhaney committed Feb 5, 2021
1 parent aefe66e commit 90a788d
Showing 1 changed file with 18 additions and 10 deletions.
28 changes: 18 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing

Among billions other things you can do with your time, you choose to spend it on our little extension, how extraordinary!🎉 Thank you!
Among billions other things you can do with your time, you choose to spend it on our little extension, how extraordinary!🎉 Thank you!

vscode-jest started as a simple extension and grew quite a bit in the last 12 months with many amazing contributions from the community! As the community and code base continue to expand, we decided to restructure the contribution page to make it easier and more fun to contribute:

Expand All @@ -9,7 +9,8 @@ vscode-jest started as a simple extension and grew quite a bit in the last 12 mo
1. [How to Contribute](#how_to_contribute): tips on how to setup your local vscode-jest development environment; as well as test and debug it before submission.

## Code of Conduct
We adopt the standard open source [contributor covenant](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html).

We adopt the standard open source [contributor covenant](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html).

_(If you have contributed to any open source project before, you already knew it; otherwise, we recommend a quick read above.)_

Expand All @@ -18,15 +19,18 @@ _(If you have contributed to any open source project before, you already knew it
As the functionality grows, inevitably, so is the complexity. In order for this little extension continues to be stable and useful, as well as pleasant and fun to work with for the current and future contributors, we sometimes had to make hard trade-off choices between functionality and complexity. The following principles help to guide these decisions...

### Principle \#1: be a good extension

Sure, but what does that really mean?
- **utilize vscode platform as much as possible**, i.e. do not reinvent the wheel; do not force users to learn our way of doing the same thing. A good extension should be *intuitive*, i.e. what they learned from the platform should just apply in our extension.

- **utilize vscode platform as much as possible**, i.e. do not reinvent the wheel; do not force users to learn our way of doing the same thing. A good extension should be _intuitive_, i.e. what they learned from the platform should just apply in our extension.
- **fix root causes**: it is tempting to fix issues in the extension when the root cause is actually in vscode, jest or other dependent packages. It is almost always better to address them in their corresponding packages, 1) it benefit more people, an open source spirit 2) it keeps vscode-jest clean and focus on our core competency.
- **being adaptive to user environment**: js development environment is dynamic and complex, while we work hard to make the tool easy to use, there is no illusion that we can cover every use case, configuration, or framework used. When facing introducing extra logic and external assumptions for retrieving user-environment specific info, we favor configuration based solution. Not only users can easily adapt vscode-jest to their specific environments, with the precision and performance we can never match; vscode-jest can stay clean and simple.

### Principle \#2: be a good developer tool

- **do not block**: as a developer, I think we all have encountered the frustrating experience that the tool supposed to boost our productivity became the very thing to block our progress. Think about the failure scenario, can user unblock themselves if my code failed?
- **help users to help themselves**: show status, meaningful error messages, instructions on how they can fix or customize are sometimes more important than codes. Do not under estimate the importance of documentation, feel free to submit document changes along with your PR.
- **be courteous of all users' time**: every feature, however useful for those who use it, could be a burden for others that don't need it. Consider costly operation on-demand, deferred until needed, options to turn on/off etc.
- **be courteous of all users' time**: every feature, however useful for those who use it, could be a burden for others that don't need it. Consider costly operation on-demand, deferred until needed, options to turn on/off etc.

### Principle \#3: be easy to contribute

Expand All @@ -35,7 +39,7 @@ There are a lot of things we can do in this area, and this document is part of i
But maybe more importantly, every contributor can play a critical role here. Nobody enjoys working with spaghetti code that breaks easily and difficult to read. While it is fun and exciting when adding new logic, we should all be mindful that it will impact other contributors long after our commits:

- all future contributors need to read our code to understand how the system works. So keep the code simple and short, and yes comments are welcome ;-)
- once the code is in, it will need to be maintained. Therefore, keep the state as tight as possible, don't create a class variable that only used in a single method; avoid assumptions about user environments, package locations, etc; less is less, and it is often better than more ;-)
- once the code is in, it will need to be maintained. Therefore, keep the state as tight as possible, don't create a class variable that only used in a single method; avoid assumptions about user environments, package locations, etc; less is less, and it is often better than more ;-)
- safe guard your logic with tests so the future contributors will not need to worry about their change might accidentally break yours. Don't underestimate the power of search-and-replace or fat-finger effect ;-)

## How to contribute
Expand Down Expand Up @@ -84,8 +88,8 @@ As `jest-editor-support` requires running through Babel, you can run the Babel w

Yeah, it's a bit of a process, but we'll be sharing code with the nuclide team and that's worth it IMO.


### Testing and Debugging

Be kind to the reviewers and future contributors, please make sure you pass the following tests before submitting the PR:

**1. unit tests**
Expand All @@ -94,22 +98,26 @@ Make sure `yarn lint`, `yarn test` and `yarn vscode:prepublish` all work.
**2. integration tests**

There are two debugging launch configurations defined in `.vscode/launch.json`:
* Debug Tests
* Launch Extension

- Debug Tests
- Launch Extension

To debug the extension, [change the launch configuration](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) to **Launch Extension** and start debugging.

**3. eat our own dog food**

The ultimate test is to actually use it in our real day-to-day working environment for a while. There are multiple ways to do this:

- by command line: `code --extensionDevelopmentPath=your-local-vscode-jest`
- by environment variable: `CODE_EXTENSIONS_PATH`
- by symlink:

Here is a mac example:

```
$ cd ~/.vscode/extensions
$ mv Orta.vscode-jest-2.7.0 vscode.orig
$ ln -s Orta.vscode-jest-2.7.0 your-local-vscode-jest
$ mv orta.vscode-jest-4.0.0 vscode.orig
$ ln -s your-local-vscode-jest orta.vscode-jest-4.0.0
```

restore vscode.orig when you are done testing.

0 comments on commit 90a788d

Please sign in to comment.