Make sure you have at least 4 GB of physical memory allocation to your OS and 4GB swap space allocated or npm run dev will probably freeze the system.
Getting setup is easy, you'll need to have Node.js installed, then simply clone the repository and within the working directory run the following:
# You only need to run this the first time
npm install yarn
npm run yarn install
npx husky install
# Run this to start the development server and build system
npm run dev
If you get React dependency errors with npm install yarn, try this instead:
sudo npm install --global yarn
If you're on Linux, you can simply type make and it will do all this for you as well.
If you're on Windows and need specific help getting tools installed and the repo cloned, see Detailed Setup Steps below.
(And ... those detailed steps may even be a useful pointer about how to get started under Linux/macOS: they're broadly applicable, even if details differ slightly.)
Once running, you can then navigate to http://dev.beta.online-go.com:8080/ which loads the interface from your local server that you just started with gulp, and connects to the beta server for testing.
- Sign up for a GitHub account.
- Search the issue tracker to see if the problem is already submitted or the request for an enhancement exists.
- Submit an issue if one does not exist. Please include as much of the below information as possible:
- A clear summary.
- Operating System tested on.
- Browser used when bug appeared (or multiple browsers if you have replicated the bug).
- Browser version.
- Steps to reproduce the issue.
- Any additional information that you might think is useful.
- Fork the repository.
- If you haven't done so, set up git.
- Clone the repository to your computer. (Found in step 2 of "keeping your fork synced" in the fork a repo help article.)
- To ensure you track the latest updates, you will want to configure git to sync your fork with the original online-go repository. (See step 3 in the same article.)
- You may need to install Git LFS if your clone doesn't complete.
- Create a branch on your local machine. Name it something that makes sense for your updates.
- This could also be done from the git bash command line.
- If you used the first method, you will need to ensure you pull down your project's remote branches.
- Make the desired changes in the code or documentation.
- Add, commit, and push your changes to your forked repository.
- Navigate to the branch you created in your forked repository on github.
- Select
New Pull Request. - Write an appropriate title and comment for the proposed updates.
- Create the pull request.
This project is largely built with TypeScript and React. If you are unfamiliar with these, please take a few minutes to familiarize yourself.
- Create a fork of online-go.com
- Have an account at github.com, login there
- Go to GitHub - online-go/online-go.com: Source code for the Online-Go.com web interface
- Press the “fork” button
-
Install VSCode
-
Install git from the windows installer: Git - Downloading Package (git-scm.com). Choose all defaults except "Configuring Line Ending Conversions". No matter what the description says, chose
checkout-as-is, commit-as-is(the description makes it sound like you would not want this) -
Download and run
nvm-setup.exefrom https://github.com/coreybutler/nvm-windows/releases -
In a command window, run
nvm install lts
npm install -g yarn
npm install -g husky
- Open VSCode
- Choose "clone git repository"
- Chose "clone from github"
- Allow it to log you into GitHub
- Choose your fork of online-go.com to clone
- make sure it's your fork - VSCode may offer the official repo at the top of the list, don't chose that one
- Chose a local folder somewhere sensible to clone it into (definitely distinct from anything left over from before!)
- Agree to install the recommended extensions (you definitely need these for OGS, they setup the editor for coding standards that are enforced, and provide linting while editing)
... you should now see a code explorer on the left pane of VSCode showing the OGS repo file structure (maybe you need to click on the top icon in the left pane to get this view).
... now you have online-go.com checked out, without silly CRLF problems!
You could poke around in src/ if you are already curious
- in a command window, cd to the folder that was created when you cloned the repo and do
yarn
npm run dev
This should result in a bunch of packages being installed, then a server starting up and telling you it's running
Navigate to localhost:8080 in your browser and hopefully see your local checkout rendering the Beta server....
... and if that works, we have VSCode done and ready to edit something.
You can immediately edit something:
- Click on the search magnifying glass top left pane of VSCode
- Type
no games being playedinto the search bar
It should show you where this string is in ObserveGamesComponent.tsx.
- click on that to be taken to that place in the code
- Edit the string, save the file
- See in the browser that string update on the "Watch" page that was open.
🎉 you made an edit to OGS UI.
- Commit your change (locally)
You will want to commit your changes regularly locally. To prepare for this you need to make a branch for them.
This is easiest done in VSCode - down the bottom left is a label telling you what branch you are in fact on now. It has the "source control" symbol (branchy thing) and the name of the branch. To make a branch and commit to it:
- Click the branch label
- "Create a branch"
- Give it a name
Then
- Click on the "source control" symbol in the left pane (select git actions)
- Type a meaningful commit message in the obvious message entry place
- click commit
Do the last three steps often :slight_smile:
- Publish your change (to GitHub)
When your change is ready for incorporation into OGS:
- Click "source control" in the left
- Click "publish change"
Note: it might be saying "Sync" instead of "Publish" - this means that GitHub knows about your branch already from something you did previously, that's OK.
🎉 Now your code is available ready for a Pull Request into the main repo.