-
Notifications
You must be signed in to change notification settings - Fork 38
How to Contribute
There are many ways to contribute to the Haystack project: logging bugs, submitting pull requests, reporting issues, and creating suggestions.
After cloning and building the repo, check out the issues list. Issues labeled help wanted are good issues to submit a PR for. Issues labeled as a good first issue are great candidates to pick up if you are in the code for the first time. If you are contributing significant changes, or if the issue is already assigned to a specific month milestone, please discuss with the assignee of the issue first before starting to work on the issue.
In order to download necessary tools, clone the repository, and install dependencies via npm, you need network access. You'll need the following tools:
- [VERY IMPORTANT] Our modified pixi js
- Our pixi js repo holds a modified form of the pixijs library. You must clone it into the same directory that
haystack-editorhas been cloned into. - You must build the pixi repo (
npm i,npm run build) - After cloning and building this repo, run
build-scripts/edit-npm-modules.shin the haystack-editor repo. This will copy several files from our pixi repo into your node_modules- You should re-run
build-scripts/edit-npm-modules.shwhenever you runyarninhaystack-editor - Don't bother doing this until after you've run
yarninhaystack-editorfor the first time. Otherwise, yournode_modulesdirectory won't exist and nothing will happen
- You should re-run
- Our pixi js repo holds a modified form of the pixijs library. You must clone it into the same directory that
- Git
-
Node.JS, x64 or ARM64, version >=20.x
- Windows: do not pick the option to install Windows Build Tools, see the step below for instructions
-
Python (required for node-gyp; check the node-gyp readme for the currently supported Python versions)
- Note: make sure python can run from a command line prompt without error
- A C/C++ compiler tool chain for your platform:
- Windows 10/11 (x64 or ARM64)
- Install the Visual C++ Build Environment by either installing the Visual Studio Build Tools or the Visual Studio Community Edition. The minimum workload to install is Desktop Development with C++. But there are additional components from "Individual components":
- MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest) (use ARM64 for Windows on ARM, but the x64/x86 may still be needed)
- C++ ATL for latest build tools with Spectre Mitigations
- C++ MFC for latest build tools with Spectre Mitigations
- note: for Windows on ARM, you may need to specify the version to v14.41-17.11, rather than (latest), and also the MSVC v143 - VS 2022 C++ build tools.
- open a command prompt and run npm config edit and add or modify the msvs_version setting equal to your vs version. (e.g. msvs_version=2022 for visual studio 2022)
- Warning: Make sure your profile path only contains ASCII letters, e.g. John, otherwise, it can lead to node-gyp usage problems (nodejs/node-gyp/issues#297)
- Note: Building and debugging via the Windows subsystem for Linux (WSL) is currently not supported.
- Install the Visual C++ Build Environment by either installing the Visual Studio Build Tools or the Visual Studio Community Edition. The minimum workload to install is Desktop Development with C++. But there are additional components from "Individual components":
- Windows WSL2: https://github.com/microsoft/vscode/wiki/Selfhosting-on-Windows-WSL
- macOS
-
Xcode and the Command Line Tools, which will install gcc and the related toolchain containing make
- Run xcode-select --install to install the Command Line Tools
-
Xcode and the Command Line Tools, which will install gcc and the related toolchain containing make
- Linux
- On Debian-based Linux: sudo apt-get install build-essential g++ libx11-dev libxkbfile-dev libsecret-1-dev libkrb5-dev python-is-python3
- On Red Hat-based Linux: sudo yum groupinstall "Development Tools" && sudo yum install libX11-devel.x86_64 libxkbfile-devel.x86_64 libsecret-devel krb5-devel # or .i686.
- Others:
- make
- pkg-config
- GCC or another compile toolchain
- Building deb and rpm packages requires fakeroot and rpm; run: sudo apt-get install fakeroot rpm
- Windows 10/11 (x64 or ARM64)
In case of issues, try deleting the contents of ~/.node-gyp (alternatively ~/.cache/node-gyp for Linux, ~/Library/Caches/node-gyp/ for macOS, or %USERPROFILE%\AppData\Local\node-gyp for Windows) first and then run git clean -xfd and then try again.
Note: For more information on how to install NPM modules globally on UNIX systems without resorting to sudo, refer to this guide.
If you are using npm >= 10.2.3 or node-gyp >= 10.0.0, then you might see error when building native modules of this project
Spectre-mitigated libraries are required for this project. To fix this error open the Haystack Installer, add the following components corresponding to the architecture you are building for (x64/ARM/ARM64) and restart your build session
- MSVC Spectre-mitigated libs (latest)
- C++ ATL for latest build tools with Spectre Mitigations
- C++ MFC for latest build tools with Spectre Mitigations
Install and build all of the dependencies using yarn:
cd haystack-editor
yarn
Then you have two options:
- If you want to build from inside Haystack, you can open the haystack-editor folder and start the build task with Ctrl+Shift+B (CMD+Shift+B on macOS). The build task will stay running in the background even if you close Haystack. If you happen to close Haystack and open it again, just resume the build by pressing Ctrl+Shift+B (CMD+Shift+B) again. You can kill it by running the Kill Build Haystack task or pressing Ctrl+D in the task terminal.
- If you want to build from a terminal, run
yarn watch. This will run both the core watch task and watch-extension tasks in a single terminal.
The incremental builder will do an initial full build and will display a message that includes the phrase "Finished compilation" once the initial build is complete. The builder will watch for file changes and compile those changes incrementally, giving you a fast, iterative coding experience.
- Windows: If you have installed Visual Studio 2017 as your build tool, you need to open x64 Native Tools Command Prompt for VS 2017. Do not confuse it with VS2015 x64 Native Tools Command Prompt, if installed.
- Linux: You may hit a ENOSPC error when running the build. To get around this follow instructions in the Common Questions.
If the build step fails, or if the built version fails to run (see next section), run
git clean -xfdin yourhaystack-editorfolder, then re-runyarn.
Errors and warnings will show in the console while developing Haystack. If you use Haystack to develop Haystack, errors and warnings are shown in the status bar at the bottom left of the editor. You can view the error list using View | Errors and Warnings or pressing Ctrl+P and then ! (CMD+P and ! on macOS).
👉 Tip! You don't need to stop and restart the development version of Haystack after each change. You can just execute Reload Window from the command palette. We like to assign the keyboard shortcut Ctrl+R (CMD+R on macOS) to this command.
To test the changes, you launch a development version of Haystack on the workspace haystack-editor, which you are currently editing.
Running on Electron with extensions run in NodeJS: macOS and Linux
./scripts/haystack-editor.sh
Windows
.\scripts\haystack-editor.bat
👉 Tip! If you receive an error stating that the app is not a valid Electron app, it probably means you didn't run yarn watch first.
👉 Tip! If you see a blank screen when Haystack loads, consider whether you have executed the pixi js steps in the Prerequisites: https://github.com/haystackeditor/haystack-editor/wiki/How-to-Contribute#prerequisites. You might have to run build-scripts/edit-npm-modules.sh again.
Haystack has a multi-process architecture and your code is executed in different processes. The render process runs the UI code inside the Shell window. To debug code running in the render you can either use Haystack or the Chrome Developer Tools.
Open the haystack-editor repository folder Choose the Haystack Editor launch configuration from the launch dropdown in the Debug viewlet and press F5.
Run the Developer: Toggle Developer Tools command from the Command Palette in your development instance of Haystack to launch the Chrome tools. It's also possible to debug the released versions of Haystack, since the sources link to sourcemaps hosted online.
The extension host process runs code implemented by a plugin. To debug extensions (including those packaged with Haystack) which run in the extension host process, you can use Haystack itself. Switch to the Debug viewlet, choose the Attach to Extension Host configuration, and press F5. The search process can be debugged, but must first be started. Before attempting to attach, start a search by pressing Ctrl+P (CMD+P on macOS), otherwise, attaching will fail and time out.
Run the unit tests directly from a terminal by running ./scripts/test.sh from the haystack-editor folder (scripts\test on Windows). We'll add more details on how to run and debug tests.
Run the tests directly from a terminal by running ./scripts/test.sh from the haystack-editor folder (scripts\test on Windows). The test README has complete details on how to run and debug tests, as well as how to produce coverage reports.
We use eslint and prettier for linting our sources. You can run eslint across the sources by calling npm run eslint from a terminal or command prompt. You can also run npm run eslint as a Haystack task by pressing Ctrl+P (CMD+P on macOS) and entering task eslint.
To lint the source as you make changes you can install the eslint extension and the prettier extension.
No marketplace is available from the haystack open source builds. If you need to use or debug an extension you can check to see if the extension author publishes builds in their repository (check the Builds page) or if it is open source you can clone and build the extension locally. Once you have the .VSIX, you can "side load" the extension either through the command line or using Install from VSIX command in the Extensions View command drop-down (see more on command line extension management).
To enable us to quickly review and accept your pull requests, always create one pull request per issue and link the issue in the pull request. Never merge multiple requests in one unless they have the same root cause. Be sure keep code changes as small as possible. Avoid pure formatting changes to code that has not been modified otherwise. Pull requests should contain tests whenever possible.
Check out the full issues list for a list of all potential areas for contributions. Note that just because an issue exists in the repository does not mean we will accept a contribution to the core editor for it. There are several reasons we may not accept a pull request like:
- Performance - One of Haystack’s core values is to deliver a lightweight code editor, that means it should perform well in both real and perceived performance.
- User experience - Since we want to deliver a lightweight code editor, the UX should feel lightweight as well and not be cluttered. Most changes to the UI should go through the issue owner and/or the UX team.
- Architectural - The team and/or feature owner needs to agree with any architectural impact a change may make. Things like new extension APIs must be discussed with and agreed upon by the feature owner.
To improve the chances to get a pull request merged you should select an issue that is labelled with the
help wantedorbuglabels. If the issue you want to work on is not labelled withhelp-wantedorbug, you can start a conversation with the issue owner asking whether an external contribution will be considered. To avoid multiple pull requests resolving the same issue, let others know you are working on it by saying so in a comment.
Haystack can be packaged for the following platforms: win32-ia32 | win32-x64 | darwin-x64 | darwin-arm64 | linux-ia32 | linux-x64 | linux-arm These gulp tasks are available: haystack-editor-[platform]: Builds a packaged version for [platform]. haystack-editor-[platform]-min: Builds a packaged and minified version for [platform]. 👉 Tip! Run gulp via npm to avoid potential out of memory issues, for example npm run gulp haystack-editor-linux-x64 See also: Cross-Compiling for Debian-based Linux
We're also interested in your feedback for the future of Haystack. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.
In order to keep the conversation clear and transparent, please limit discussion to English and keep things on topic with the issue. Be considerate to others and try to be courteous and professional at all times.