Skip to content

Contributing

Jump to bottom
Adam Hooper edited this page Jul 12, 2019 · 9 revisions

Here's how to change Workbench cope:

  1. Talk with us! File an issue on GitHub or join us on Gitter and let's get excited about what you want to do.
  2. Fork this repo, as per GitHub's forking documentation:
    1. Click "Fork"
    2. Clone your fork
    3. Set up your development environment
    4. git remote add upstream https://github.com/CJWorkbench/cjworkbench (so you can track our master branch later)
  3. Create your change:
    1. Make sure your master is the same as upstream/master:
      1. git fetch upstream
      2. git checkout master
      3. git pull
      4. git merge --ff-only upstream/master (or git reset --hard upstream/master if you wrote changes to master accidentally and wish to delete them)
    2. git checkout master
    3. Create a new branch: git branch my-great-feature
    4. Write a test that fails (bin/dev unittest, bin/dev npm test, bin/integration-test)
    5. Write code until the test passes
    6. bin/dev reformat-code to conform to our coding style
    7. bin/integration-test to ensure you haven't broken something critical
    8. Commit with a commit message referencing the GitHub issue
  4. Submit a pull request:
    1. git push origin my-great-feature
    2. Browse to https://github.com/CJWorkbench/cjworkbench and submit a pull request for your branch
  5. Iterate! We'll review your code; we may ask questions or propose changes. We may ask you to add commits to your pull request; we may also ask you to merge or rebase from our master.

Tools that can help you

Black

Workbench's Python code follows Black conventions. Workbench won't build images (and so bin/dev integration-test will fail) if your code isn't byte-perfect. Integrate Black with your text editor to avoid silly mistakes: for instance, you can configure your editor to run black on a file automatically when saving.

StandardJS

Workbench's JavaScript code follows StandardJS conventions. Workbench won't build images (and so bin/dev integration-test will fail) if your code isn't byte-perfect. Integrate StandardJS with your text editor to avoid silly mistakes: for instance, you can configure your editor to run standard --fix on a file automatically while saving.

Editor-specific notes

nvim

These plugins and configuration will make Neovim offer autocomplete suggestions, check code against a language server (warning on unused imports, typos, etc), and auto-reformat files on save.

Since dependencies are installed into Docker containers, the configuration depends on Docker containers, too. Docker images will be built on first use: their Dockerfiles are in the docker/ subdirectory of this repository.

Here's some copy/pasteable code for your ~/.config/nvim/init.vim. It depends on vim-plug.

call plug#begin('~/.local/share/nvim/plugged')
Plug 'w0rp/ale'
Plug 'Shougo/deoplete.nvim'
call plug#end()

" Assume cjworkbench is cloned at ~/src/cjworkbench/cjworkbench/
" (and modules are in ~/src/cjworkbench/modulename/, etc.)
let s:cjworkbench_dir = $HOME.'/src/cjworkbench'

if getcwd() =~ s:cjworkbench_dir.'/'
  au FileType python,javascript nnoremap K :ALEHover<CR>
  au FileType python,javascript nnoremap <C-g>d :ALEGoToDefinition<CR>
  au FileType python,javascript nnoremap <C-g>r :ALEFindReferences<CR>

  let g:deoplete#enable_at_startup = 1
  let g:deoplete#min_pattern_length = 0
  let g:ale_set_quickfix = 1
  let g:deoplete#sources = {'_': ['ale']}
  " Global executables won't work: we want to run within Docker containers.
  let g:ale_use_global_executables = 0
  let g:ale_javascript_tsserver_executable = s:cjworkbench_dir.'/cjworkbench/docker/tsserver/run.sh'
  let g:ale_python_pyls_executable = s:cjworkbench_dir.'/cjworkbench/docker/lsp/python/run.sh'
  let g:ale_python_black_executable = s:cjworkbench_dir.'/cjworkbench/docker/lsp/python/black.sh'
  let g:ale_linters_explicit = 1
  let g:ale_linters = {
  \   'javascript': ['tsserver'],
  \   'python': ['pyls'],
  \}
  let g:ale_fix_on_save = 1
  " ale's 'standard' plugin relies on tmpfiles that don't get passed to
  " Docker. Build our own 'standard' command.
  let g:ale_fixers = {
  \   'javascript': [{buffer -> {'command': s:cjworkbench_dir.'/cjworkbench/docker/tsserver/standard.sh'}}],
  \   'python': ['black'],
  \}
endif

In nvim, run :PlugInstall to install the plugins. Then whenever you start nvim from within ~/src/cjworkbench/, the CJWorkbench rules will apply. On your first load of a Python file and your first load of a JavaScript file, docker build will run; that will take a few minutes and download a few hundred MB.

Clone this wiki locally