From d58f4bebf97e2ad9e7dc86a22cff9ab3fd0079b4 Mon Sep 17 00:00:00 2001 From: nmalky Date: Mon, 19 Mar 2018 20:02:40 +0000 Subject: [PATCH 1/9] Create how-to-contribute-code.md See https://github.com/sourcebots/volunteer-docs/issues/2 --- content/essential-knowledge/how-to-contribute-code.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 content/essential-knowledge/how-to-contribute-code.md diff --git a/content/essential-knowledge/how-to-contribute-code.md b/content/essential-knowledge/how-to-contribute-code.md new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/content/essential-knowledge/how-to-contribute-code.md @@ -0,0 +1 @@ + From 0f74403c65760fdae3ea819fff567c014f0fa4b3 Mon Sep 17 00:00:00 2001 From: Henry Oliver Edwards <32649829+BitBait@users.noreply.github.com> Date: Mon, 19 Mar 2018 21:18:13 +0000 Subject: [PATCH 2/9] Adding content for wiki This isn't formatted properly --- .../how-to-contribute-code.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/content/essential-knowledge/how-to-contribute-code.md b/content/essential-knowledge/how-to-contribute-code.md index 8b13789..2fa247d 100644 --- a/content/essential-knowledge/how-to-contribute-code.md +++ b/content/essential-knowledge/how-to-contribute-code.md @@ -1 +1,37 @@ +A guide on how to contribute code +## How to set up github +## How to choose something to work on +## Encouragement to make small changes +## How to make a small change (e.g. to website / docs) using GitHub online editor: *all* the steps. Make a commit to a new branch, submit a PR. In detail, for people who have never used git. +## How to set up git on your local machine +## Using git by CLI / GitHub desktop app (e.g. adding some code) +## Conventions for PRs, commits, comments + +More advanced: +* Code review (?) +* Setting up dev environment + +--- +title : How to set up git on your local machine +--- + +# Linux +For Debian based systems +```sudo apt-get update +sudo apt-get upgrade +sudo apt-get install git``` + +For Red Hat based systems +`sudo yum upgrade` +`sudo yum install git` + +# Mac +Open terminal and type the following +'ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +brew doctor' + + + +# SourceBots Volunteer Documentation +This documentation contains information about how to setup github on your local machine From b3a57e1b275eafe2dfe5ba6c3de6e6c349976435 Mon Sep 17 00:00:00 2001 From: Henry Oliver Edwards <32649829+BitBait@users.noreply.github.com> Date: Mon, 19 Mar 2018 21:38:19 +0000 Subject: [PATCH 3/9] Update how-to-contribute.md Added windows, added git kraken however i'm not sure if this is the the best choice for just getting git setup on windows, hopefully someone with more experience can edit this --- .../how-to-contribute-code.md | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/content/essential-knowledge/how-to-contribute-code.md b/content/essential-knowledge/how-to-contribute-code.md index 2fa247d..3e4a1d2 100644 --- a/content/essential-knowledge/how-to-contribute-code.md +++ b/content/essential-knowledge/how-to-contribute-code.md @@ -18,19 +18,30 @@ title : How to set up git on your local machine # Linux For Debian based systems + ```sudo apt-get update sudo apt-get upgrade -sudo apt-get install git``` +sudo apt-get install git +``` For Red Hat based systems -`sudo yum upgrade` -`sudo yum install git` + +```sudo yum upgrade +sudo yum install git +``` + # Mac Open terminal and type the following -'ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -brew doctor' +```ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +brew doctor +brew install git +``` + +# Windows +We recommend getting git kraken from [download page](https://www.gitkraken.com/), run the +.exe (can someone else fill this in please) # SourceBots Volunteer Documentation From e34c32f3945c3ad74f27c2ef89323120cb0facf2 Mon Sep 17 00:00:00 2001 From: nmalky Date: Mon, 19 Mar 2018 22:45:57 +0000 Subject: [PATCH 4/9] Added some more detail on how to get started Still needs to be merged with the platform-specific git instructions. --- .../how-to-contribute-code.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/content/essential-knowledge/how-to-contribute-code.md b/content/essential-knowledge/how-to-contribute-code.md index 3e4a1d2..0d33e0a 100644 --- a/content/essential-knowledge/how-to-contribute-code.md +++ b/content/essential-knowledge/how-to-contribute-code.md @@ -1,10 +1,25 @@ -A guide on how to contribute code +# A guide on how to contribute code + +Welcome! If you're new to GitHub and open source, it can seem quite difficult to get started. +Here is a step-by-step guide on how to contribute code to the SourceBots project! + +## How to set up GitHub +Create a GitHub account: https://github.com/join + +It's useful to stay logged in, so it's as easy as possible to keep up to date and make contributions -## How to set up github ## How to choose something to work on +Have a look at [TODO: find page] + ## Encouragement to make small changes +We encourage you to make any changes, however small. e.g. if you spot a spelling error somewhere, why not fix it and make a pull request? This is a good way to familiarise yourself with the process, and is a good stepping stone towards larger contributions. + ## How to make a small change (e.g. to website / docs) using GitHub online editor: *all* the steps. Make a commit to a new branch, submit a PR. In detail, for people who have never used git. +TODO. + ## How to set up git on your local machine +TODO: join this with the later documentation. + perhaps add an external guide + ## Using git by CLI / GitHub desktop app (e.g. adding some code) ## Conventions for PRs, commits, comments From f9761524bc821fad6530685441cbe132c38f5286 Mon Sep 17 00:00:00 2001 From: nmalky Date: Tue, 20 Mar 2018 10:19:02 +0000 Subject: [PATCH 5/9] Updated based on latest review; clarified structure Fixed some issues with the content about setting up git/GitHub Added TODOs to indicate what each section should include Fixed some spelling/grammar Didn't change: any structure/content under title : How to set up git on your local machine I think all the information here is now under ## How to set up git on your local machine, so it is safe to remove now? --- .../how-to-contribute-code.md | 20 +++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/content/essential-knowledge/how-to-contribute-code.md b/content/essential-knowledge/how-to-contribute-code.md index 0d33e0a..386fdf3 100644 --- a/content/essential-knowledge/how-to-contribute-code.md +++ b/content/essential-knowledge/how-to-contribute-code.md @@ -4,9 +4,9 @@ Welcome! If you're new to GitHub and open source, it can seem quite difficult to Here is a step-by-step guide on how to contribute code to the SourceBots project! ## How to set up GitHub -Create a GitHub account: https://github.com/join +Create a GitHub account: https://github.com/join, or log in if you already have an account. -It's useful to stay logged in, so it's as easy as possible to keep up to date and make contributions +It's useful to stay logged in, so it's as easy as possible to keep up to date and make contributions. ## How to choose something to work on Have a look at [TODO: find page] @@ -18,9 +18,21 @@ We encourage you to make any changes, however small. e.g. if you spot a spelling TODO. ## How to set up git on your local machine -TODO: join this with the later documentation. + perhaps add an external guide +To make more advanced changes, it may be necessary to install and set up git on your local machine. +To install git, see https://git-scm.com/book/en/v2/Getting-Started-Installing-Git. + +TODO: +* adding ssh keys, where relevant +* adding GitHub auth tokens, where relevant +* ? does the GitHub desktop app, or GitKraken, or other IDEs guide you through this process well? Subsections maybe ## Using git by CLI / GitHub desktop app (e.g. adding some code) +TODO: +* setting up a new branch +* how to make a commit +* how to push to a branch + + ## Conventions for PRs, commits, comments More advanced: @@ -55,7 +67,7 @@ brew install git # Windows -We recommend getting git kraken from [download page](https://www.gitkraken.com/), run the +We recommend getting GitKraken from [download page](https://www.gitkraken.com/), run the .exe (can someone else fill this in please) From 641e556ddceec2c491040e3e9da4688e71c4f66d Mon Sep 17 00:00:00 2001 From: nmalky Date: Tue, 20 Mar 2018 10:45:16 +0000 Subject: [PATCH 6/9] Remove duplicated "how to setup/install" section --- .../how-to-contribute-code.md | 35 ------------------- 1 file changed, 35 deletions(-) diff --git a/content/essential-knowledge/how-to-contribute-code.md b/content/essential-knowledge/how-to-contribute-code.md index 386fdf3..731ad83 100644 --- a/content/essential-knowledge/how-to-contribute-code.md +++ b/content/essential-knowledge/how-to-contribute-code.md @@ -38,38 +38,3 @@ TODO: More advanced: * Code review (?) * Setting up dev environment - ---- -title : How to set up git on your local machine ---- - -# Linux -For Debian based systems - -```sudo apt-get update -sudo apt-get upgrade -sudo apt-get install git -``` - -For Red Hat based systems - -```sudo yum upgrade -sudo yum install git -``` - - -# Mac -Open terminal and type the following -```ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -brew doctor -brew install git -``` - - -# Windows -We recommend getting GitKraken from [download page](https://www.gitkraken.com/), run the -.exe (can someone else fill this in please) - - -# SourceBots Volunteer Documentation -This documentation contains information about how to setup github on your local machine From 1372142be9e044c36de33e6a0367be2ae6555051 Mon Sep 17 00:00:00 2001 From: nmalky Date: Tue, 20 Mar 2018 10:58:46 +0000 Subject: [PATCH 7/9] Markdown'd link, added more steps/notes --- content/essential-knowledge/how-to-contribute-code.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/essential-knowledge/how-to-contribute-code.md b/content/essential-knowledge/how-to-contribute-code.md index 386fdf3..4940026 100644 --- a/content/essential-knowledge/how-to-contribute-code.md +++ b/content/essential-knowledge/how-to-contribute-code.md @@ -4,7 +4,7 @@ Welcome! If you're new to GitHub and open source, it can seem quite difficult to Here is a step-by-step guide on how to contribute code to the SourceBots project! ## How to set up GitHub -Create a GitHub account: https://github.com/join, or log in if you already have an account. +[Create a GitHub account](https://github.com/join), or log in if you already have an account. It's useful to stay logged in, so it's as easy as possible to keep up to date and make contributions. @@ -16,6 +16,8 @@ We encourage you to make any changes, however small. e.g. if you spot a spelling ## How to make a small change (e.g. to website / docs) using GitHub online editor: *all* the steps. Make a commit to a new branch, submit a PR. In detail, for people who have never used git. TODO. +* becoming a member of SourceBots organisation +* setting up a new branch on the SourceBots repo (not creating a fork) ## How to set up git on your local machine To make more advanced changes, it may be necessary to install and set up git on your local machine. @@ -28,7 +30,7 @@ TODO: ## Using git by CLI / GitHub desktop app (e.g. adding some code) TODO: -* setting up a new branch +* setting up a new branch on the SourceBots repo (not creating a fork) * how to make a commit * how to push to a branch From 5af9b17f2dbb44a9e09632c3ab0d49b0e59e80e0 Mon Sep 17 00:00:00 2001 From: nmalky Date: Wed, 21 Mar 2018 01:18:12 +0000 Subject: [PATCH 8/9] Added more steps on GitHub web contributions; TODOs May need reworking the order. Needs comments on the workflow. -> Will create an issue. --- .../how-to-contribute-code.md | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/content/essential-knowledge/how-to-contribute-code.md b/content/essential-knowledge/how-to-contribute-code.md index f5808ae..8f93a73 100644 --- a/content/essential-knowledge/how-to-contribute-code.md +++ b/content/essential-knowledge/how-to-contribute-code.md @@ -14,10 +14,30 @@ Have a look at [TODO: find page] ## Encouragement to make small changes We encourage you to make any changes, however small. e.g. if you spot a spelling error somewhere, why not fix it and make a pull request? This is a good way to familiarise yourself with the process, and is a good stepping stone towards larger contributions. -## How to make a small change (e.g. to website / docs) using GitHub online editor: *all* the steps. Make a commit to a new branch, submit a PR. In detail, for people who have never used git. -TODO. +## How to make a small change (e.g. to website / docs) using GitHub online editor: + +Suppose you have a file you'd like to change. Then, + +TODO: *all* the steps. Make a commit to a new branch, submit a PR. In detail, for people who have never used git. + * becoming a member of SourceBots organisation * setting up a new branch on the SourceBots repo (not creating a fork) +- or, depending on our contribution system, creating a fork. +* making an edit (with the pencil icon) -> set up a new branch, if you haven't already. +Naming the branch. +You can't push to master. +This might create a fork automatically for you if you're not a member of the [SourceBots organisation](https://github.com/sourcebots). +* committing the changes (with meaningful commit message + description) +* adding more changes to your branch (flat structure: don't create a sub-branch (terminology?) and do a PR from sub-branch -> your new branch?) +* creating a pull request (TODO: when?) +* waiting for someone to review your code (and/or asking for feedback, perhaps on the slack) +* committing more changes, completing the review process + +TODO: put these TODOs in more appropriate places other than in the document itself? + +TODO: link to a good guide (with more detail) about this. But it's good to have our own version for making minimal commits and PRs for *our* specific workflow. It's also a useful way for people like myself to learn by writing. + +TODO: include *tip* boxes? For tangential but useful information/explanation about the general principles behind e.g. commits, forks, branches, and more complete guides/exceptions about when to do different things. (Or, in another style? By an example of a project with good documentation) ## How to set up git on your local machine To make more advanced changes, it may be necessary to install and set up git on your local machine. From cf37fb063e72a29a69c6fd36aaa154dfb83325e3 Mon Sep 17 00:00:00 2001 From: nmalky Date: Wed, 21 Mar 2018 21:45:57 +0000 Subject: [PATCH 9/9] Make lists of bullet points render properly Actually use markdown paragraphs properly. https://daringfireball.net/projects/markdown/syntax#list --- content/essential-knowledge/how-to-contribute-code.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/essential-knowledge/how-to-contribute-code.md b/content/essential-knowledge/how-to-contribute-code.md index 8f93a73..c373de7 100644 --- a/content/essential-knowledge/how-to-contribute-code.md +++ b/content/essential-knowledge/how-to-contribute-code.md @@ -44,12 +44,14 @@ To make more advanced changes, it may be necessary to install and set up git on To install git, see https://git-scm.com/book/en/v2/Getting-Started-Installing-Git. TODO: + * adding ssh keys, where relevant * adding GitHub auth tokens, where relevant * ? does the GitHub desktop app, or GitKraken, or other IDEs guide you through this process well? Subsections maybe ## Using git by CLI / GitHub desktop app (e.g. adding some code) TODO: + * setting up a new branch on the SourceBots repo (not creating a fork) * how to make a commit * how to push to a branch @@ -58,5 +60,6 @@ TODO: ## Conventions for PRs, commits, comments More advanced: + * Code review (?) * Setting up dev environment