232 lines
7.5 KiB
Markdown
232 lines
7.5 KiB
Markdown
# Contributing
|
||
|
||
## Index
|
||
* [Troubleshooting](CONTRIBUTING.md#troubleshooting)
|
||
* [Code Contributions](CONTRIBUTING.md#code-contributions)
|
||
* [Keeping a Fork Up-to-date](CONTRIBUTING.md#keeping-a-fork-up-to-date)
|
||
* [Running Local Development Server](CONTRIBUTING.md#running-local-development-server)
|
||
* [Running Production Build](CONTRIBUTING.md#running-production-build)
|
||
* [Build Desktop Apps](CONTRIBUTING.md#build-desktop-apps)
|
||
* [Localization](CONTRIBUTING.md#localization)
|
||
* [Translation Validation](CONTRIBUTING.md#translation-validation)
|
||
|
||
## Troubleshooting
|
||
|
||
https://github.com/cncjs/cncjs/wiki/Troubleshooting
|
||
|
||
## Code Contributions
|
||
|
||
### Step 1: Fork
|
||
|
||
Fork the project [on GitHub](https://github.com/cncjs/cncjs) and check out your copy locally.
|
||
|
||
|
||
|
||
```bash
|
||
$ git clone git@github.com:username/cncjs.git
|
||
$ cd cncjs
|
||
$ git remote add upstream git://github.com/cncjs/cncjs.git
|
||
```
|
||
|
||
### Step 2: Branch
|
||
|
||
Create a feature branch and before starting:
|
||
```bash
|
||
$ git checkout -b my-feature-branch -t origin/master
|
||
```
|
||
|
||
### Step 3: Install
|
||
|
||
Run `npm install` to install the dependencies in the local node_modules folder:
|
||
```bash
|
||
$ npm install -g npm
|
||
$ npm install
|
||
```
|
||
|
||
### Step 4: Commit
|
||
|
||
Make sure git knows your name and email address:
|
||
```bash
|
||
$ git config --global user.name "User Name"
|
||
$ git config --global user.email "user.email@example.com"
|
||
```
|
||
|
||
Writing good commit logs is important. A commit log should describe what changed and why.
|
||
|
||
### Step 5: Rebase
|
||
|
||
Use `git rebase` (not `git merge`) to sync your work from time to time.
|
||
```bash
|
||
$ git fetch upstream
|
||
$ git rebase upstream/master
|
||
```
|
||
|
||
### Step 6: Build
|
||
|
||
Run `npm run prepare` to make sure the build succeed:
|
||
```bash
|
||
$ npm run prepare
|
||
```
|
||
|
||
### Step 7: Push
|
||
|
||
```bash
|
||
$ git push origin my-feature-branch
|
||
```
|
||
|
||
Go to https://github.com/username/cncjs and select your feature branch. Click on the <kbd>New pull request</kbd> button and fill out the form.
|
||
|
||
|
||
|
||
## Keeping a Fork Up-to-date
|
||
|
||
### Clone your fork
|
||
```bash
|
||
git clone git@github.com:USERNAME/cncjs.git
|
||
```
|
||
|
||
### Add remote from original repository in your forked repository
|
||
```bash
|
||
cd cncjs
|
||
git remote add upstream git://github.com/cncjs/cncjs.git
|
||
git fetch upstream
|
||
```
|
||
|
||
### Updating your fork from original repo to keep up with their changes
|
||
```bash
|
||
git pull upstream master
|
||
```
|
||
|
||
### Push the local branch to the remote repository
|
||
```bash
|
||
git pull origin master
|
||
git push origin master
|
||
```
|
||
|
||
## Running Local Development Server
|
||
|
||
Make sure you have Node.js 4 or later verions installed, and run `npm run dev` to start a local development server for development and testing. Every code changes will trigger webpack Hot Module Replacement (HMR) which will be really useful while developing in React.
|
||
|
||
```bash
|
||
$ npm install # Ensure that packages are installed
|
||
$ npm run dev # It may take several minutes...
|
||
: : :
|
||
Server is listening on 0.0.0.0:8000
|
||
```
|
||
|
||
Connect to http://localhost:8000 and wait until bundle finished.
|
||
```bash
|
||
webpack: wait until bundle finished: /__webpack_hmr
|
||
: : :
|
||
webpack: bundle is now VALID
|
||
```
|
||
|
||
Now you're ready to go!
|
||
|
||
## Running Production Build
|
||
|
||
```bash
|
||
$ npm install # Ensure that packages are installed
|
||
$ npm run prepare
|
||
$ ./bin/cncjs -vv
|
||
: : :
|
||
Server is listening on 0.0.0.0:8000
|
||
```
|
||
|
||
## Build Desktop Apps
|
||
|
||
#### Mac
|
||
```bash
|
||
$ npm install # Ensure that packages are installed
|
||
$ npm run prepare && npm run build:mac-x64
|
||
$ ls -al output/osx/
|
||
```
|
||
|
||
#### Windows x86
|
||
```bash
|
||
$ npm install # Ensure that packages are installed
|
||
$ npm run prepare && npm run build:win-ia32
|
||
$ ls -al output/win-ia32/
|
||
```
|
||
|
||
#### Windows x64
|
||
```bash
|
||
$ npm install # Ensure that packages are installed
|
||
$ npm run prepare && npm run build:win-x64
|
||
$ ls -al output/win/
|
||
```
|
||
|
||
#### Linux x86
|
||
```bash
|
||
$ npm install # Ensure that packages are installed
|
||
$ npm run prepare && npm run build:linux-ia32
|
||
$ ls -al output/linux-ia32/
|
||
```
|
||
|
||
#### Linux x64
|
||
```bash
|
||
$ npm install # Ensure that packages are installed
|
||
$ npm run prepare && npm run build:linux-x64
|
||
$ ls -al output/linux/
|
||
```
|
||
|
||
## Localization
|
||
|
||
If you'd like to help contribute translations, you can fork the repository, update resource files in the [src/app/i18n](https://github.com/cncjs/cncjs/tree/master/src/app/i18n) directory or in the [src/server/i18n](https://github.com/cncjs/cncjs/tree/master/src/server/i18n) directory, and create a pull request to submit your changes.
|
||
|
||
### Fork the repository
|
||
|
||
To fork the cncjs repository, click the <b>Fork</b> button in the header of the repository.
|
||
|
||
|
||
|
||
When it’s finished, you’ll be taken to your copy of the cncjs repository. Now you can update the resource files on GitHub, or clone it to your computer.
|
||
|
||
If you're using <b>GitHub for Desktop</b> application, navigate over to the toolbar, open the <b>Clone or download</b> dropdown, and click <b>Open in Desktop</b> to clone cncjs/cncjs to your computer and use it in GitHub Desktop.
|
||
|
||
|
||
|
||
### Making and pushing changes
|
||
|
||
Go ahead and make a few changes to the project using your favorite text editor. When you’re ready to submit your changes, type up a commit summary in <b>GitHub for Desktop</b>, and click <b>Commit to master</b>.
|
||
|
||
|
||
|
||
You can continue to make more changes and create new commits. When you’re ready to push your changes, click on the <b>Sync</b> button to synchronize master with the remote server.
|
||
|
||
|
||
|
||
### Creating the pull request
|
||
|
||
1. Head on over to the repository on GitHub.com where your project lives. For your example, it would be at `https://www.github.com/<your_username>/cncjs`.
|
||
|
||
|
||
2. To the right of the branch menu, click <b>New pull request</b>.<br>
|
||
|
||
|
||
3. Click <b>Create pull request</b>.
|
||
|
||
|
||
4. That's done.
|
||
|
||
## Translation Validation
|
||
|
||
You can validate the translation by copying translated resource files to the installed directory. Note that your path may differ based on the Node installation path you have in place.
|
||
```bash
|
||
$ cd $(dirname `which cncjs`)/../lib/node_modules/cncjs/dist/app/i18n/
|
||
$ pwd
|
||
/home/cheton/.nvm/versions/node/v10.15.3/lib/node_modules/cncjs/dist/app/i18n
|
||
```
|
||
|
||
To verify your changes during runtime, it's recommended that you open <b>Developer Tools</b> and disable browser cache. For example:
|
||
|
||
##### Step 1: Open Developer Tools and click [Settings]
|
||
|
||
|
||
##### Step 2: Disable cache
|
||
|
||
|
||
Now you can copy resource files to the <b>dist/cncjs/app/i18n</b> directory and refresh your browser to see new updates.
|
||
|
||
<b>Note that you should not close DevTools to make sure your browser won't cache anything.</b>
|