Skip to content
This repository was archived by the owner on Oct 28, 2022. It is now read-only.

Commit 9d596b2

Browse files
PaulL1PaulL1
committed
docs(contributing): add a first timers guide and a contributing tutorial
1 parent c21a24d commit 9d596b2

File tree

3 files changed

+331
-2
lines changed

3 files changed

+331
-2
lines changed

‎FIRST_TIMER.md

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
This guide aims to be a first principles guide for people who haven't contributed
2+
to open source before, perhaps who have limited javascript or angularJS experience,
3+
or are not familiar with the development toolset that is used for ui-grid. In short,
4+
it aims to assume you know almost nothing, and provide a set of hints, tips and links
5+
to get you going.
6+
7+
This guide covers a handful of use cases to illustrate the tools, running the tests,
8+
discuss the layout and structure of the code, and describe the process for submitting
9+
a pull request.
10+
11+
1. __A pull request to update documentation.__ This covers forking the repository,
12+
installing the base toolset, updating documentation including ngDoc and tutorials,
13+
running tests and submitting a pull request.
14+
15+
2. __A pull request to fix a code issue.__ This adds on understanding the code base,
16+
writing unit tests and writing e2e tests.
17+
18+
3. __A new feature.__ This covers the structure of a feature and some of the apis
19+
and registration logic.
20+
21+
22+
## A pull request to update documentation ##
23+
24+
We'll start with the simplest use case - imagine you're a new contributor who knows
25+
almost nothing, and wants to make a documentation change and contribute it as a
26+
pull request.
27+
28+
In order to contribute an update your basic process is:
29+
30+
- Fork the ui-grid repository in github, giving you your own copy in which you
31+
can work, and over which you have access permissions
32+
- Clone that repository
33+
- Setup the toolset on your local machine
34+
- Make the documentation changes, and verify that they look at you had hoped
35+
- Run the tests to check that nothing has broken
36+
- Commit the code to git, and push the branch to your fork
37+
- Create a pull request from your fork to the upstream repository
38+
39+
We'll go through each step in turn.
40+
41+
### Fork the ui-grid repository ###
42+
This is the easiest step. Get yourself a github logon, and navigate to the
43+
[ui-grid github page](https://github.com/angular-ui/ng-grid). Note that the
44+
actual repository still goes by the old project name of ng-grid. Click the
45+
fork button in the top left. This should navigate you to your list of
46+
projects in github, with a new fork of ui-grid (also called ng-grid in your
47+
repository list).
48+
49+
You'll see that this gives you your own issue tracker and a bunch of other content.
50+
In general you'll ignore all this, and you'll just use your fork for submitting
51+
pull requests and managing your branches.
52+
53+
### Install the base toolset ###
54+
In order to work with ui-grid you'll need some base tooling. In particular, you need
55+
git installed for version control and node.js installed to provide the npm toolset.
56+
57+
The installation process is different on each operating system, google is your friend
58+
on this one.
59+
60+
Links to try might include:
61+
62+
- http://nodejs.org/
63+
64+
### Clone the repository to your local machine ###
65+
In your github repository, on the right hand side underneath settings you'll see
66+
a box with "clone url" written in it. Copy this clone url.
67+
68+
Using the command line (terminal in OSX or linux, cmd in windows)
69+
go to the directory in which you store your projects. Type:
70+
`git clone <url you copied>`
71+
72+
__Pro-tip:__ By default github gives you an http clone address, and this will
73+
require you to log on each time you do something. Look at https://help.github.com/articles/generating-ssh-keys/
74+
for a method to use ssh keys for auto logon, or consider using the github native client.
75+
76+
This should have given you a folder on your machine into which all the ui-grid code
77+
has been copied. This is also a full git version, so it has all the git commit history
78+
inside it, within the .git folder.
79+
80+
We also want to setup a link to the upstream repository, which we use when fetching
81+
the latest code version:
82+
` cd ng-grid`
83+
` git remote add upstream https://github.com/angular-ui/ng-grid.git`
84+
85+
This allows you to get the latest code from upstream by:
86+
` git fetch upstream` or
87+
` git pull upstream`
88+
We'll discuss these steps later, for now we just want the setup done.
89+
90+
## Setup the toolset ###
91+
Before we do anything else we'll check that we can compile the code and run all
92+
the tests - if there are problems here then we want to know it's something wrong
93+
in the install rather than a change that you've made.
94+
95+
In the root folder of the project you'll see two important files:
96+
` package.json`
97+
` bower.json`
98+
These configuration files describe the dependencies for building ui-grid. Package.json
99+
tells the node package manager (npm) what to install, bower.json tells bower what to install.
100+
101+
The installation process is to first install the global packages:
102+
` npm install -g grunt-cli`
103+
If you're on a unix derived machine (OSX, Linux) you may need elevated privileges to do
104+
this install:
105+
` sudo npm install -g grunt-cli`
106+
107+
Then install the npm dependencies:
108+
` npm install`
109+
110+
Finally install the bower dependencies:
111+
` bower install`
112+
113+
Next, run the build process to verify that it builds successfully and all the unit tests
114+
pass. The build process is driven by a tool called grunt - think of this as being similar
115+
to make (for c++), rake (for ruby on rails), ant, cake, or any other build tool.
116+
117+
The core grunt configuration lives in `Gruntfile.js`, in general you shouldn't need to
118+
change this, but if you get difficulties this is where you'd trouble shoot.
119+
120+
To run a basic build, including unit tests, we can run the grunt default task:
121+
` grunt`
122+
This will syntax check the code, run the unit tests, extract the documentation using
123+
ngdocs, and put the resulting built version into the `/dist/` folder on your machine.
124+
125+
You should expect to see no errors when running this task - if you get errors then
126+
something has gone wrong. Tell us about it, and help to improve this guide by adding
127+
common errors and resolutions here:
128+
129+
- So far, no common errors.
130+
131+
Next, we want to run the end to end tests. This may require installing protractor
132+
and selenium. Start by running the grunt install task:
133+
` grunt install`
134+
Then, run the end to end tests:
135+
` grunt test:e2e`
136+
These take a while to run, be patient and make sure they're all fine.
137+
138+
Finally, run the watch task. This task watches changes you make to the filesystem, and
139+
automatically rebuilds the code. It runs a development server on port 9003 (you can get
140+
to it on your browser as http://localhost:9003), which is a local copy of the ui-grid.info
141+
site. This gives you a runnable version of the tutorials and api, and allows you to see
142+
the impact of your code changes on the tutorials.
143+
` grunt dev`
144+
Check that the tutorials are working fine on your local install.
145+
146+
__Pro-tip:__ Running grunt dev can be slow, as it automatically runs all e2e tests and
147+
unit tests on each change. You can just skip the testing by running instead `grunt dev --no-e2e`, which
148+
makes it faster, but gives you less information about where you may have broken things.
149+
Or you can edit the tests to target only the specific tests for the area you're working on.
150+
Pick the tutorial that has e2e tests and is most relevant to the area you're working in,
151+
and edit the e2e test to have `ddescribe` rather than `describe`. This will ask jasmine
152+
to run only these tests - making the testing much faster whilst still giving you some coverage.
153+
Similarly with the unit testing pick the unit test specs that relate to the module you're working on
154+
and add `ddescribe` in there. `iit` has a similar effect. Remember to take this out
155+
again before submitting a pull request.
156+
157+
### Make documentation changes ###
158+
Before making any changes, create a feature branch. This means that you branch the code
159+
base before you commit anything, and this branch is what you'll do a pull request against.
160+
` git fetch upstream`
161+
` git checkout upstream/master`
162+
` git checkout -b <my_branch_name>`
163+
This should give you a clean branch that is based off the latest upstream.
164+
165+
The documentation for ui-grid comes in three components:
166+
167+
1. The .md files within the root directory of the project. These are visible only
168+
on github, through clicking on them. They generally deal with information for a contributor,
169+
such as this guide. These can be edited directly, then submitted. They are authored in
170+
markdown format, and can only be viewed in their rendered format on github - so you edit them
171+
then push to your fork, and look at them on github.
172+
2. The tutorial files. These are in misc/tutorial/*.ngdoc, and are built by the grunt-ngdocs
173+
processor into the dist/docs/partials directory. You can preview your changes through running
174+
`grunt dev` and looking at http://localhost:9003. These are again in markdown, but in a special
175+
ngdoc version of markdown. They can include end-to-end tests, and examples that are exportable
176+
to plunkr. The biggest gotcha is being careful with where you put the ":" in the name
177+
3. The api documentation. This is extracted from the comment blocks in the javascript (`src/` folder).
178+
It uses ngdoc format and is processed by the grunt-ngdocs tool. Edits to this are done within
179+
the comment blocks in the code.
180+
181+
All of this content can be edited with a text editor.
182+
183+
The ngdoc generator has some tricks and tips. It is somewhat fussy about integrity - if you declare
184+
a method to be `@methodOf` something, then that something must exist. If it doesn't then you'll get
185+
an obscure error from grunt-ngdocs. The best advice is to save often and keep checking that it's
186+
extracting and rendering properly - then if something gives an error you'll have a good idea of what
187+
you changed. If you make bulk changes then run grunt-ngdocs, and you get an error, you'll have very
188+
poor information about where the error is within the documentation set.
189+
190+
### Run the unit and e2e tests ###
191+
As we did initially, run `grunt` to run all the unit tests, and `grunt test:e2e` to run all the end
192+
to end tests. Verify there are no errors.
193+
194+
### Push and make a pull request ###
195+
First, check that all the changes that you have made are included, and that nothing unexpected is
196+
included:
197+
` git diff` (if you've not committed yet)
198+
` git diff upstream/master` (if you have some files committed)
199+
Look through the diff listing to verify that only the changes you expected are present.
200+
201+
To commit to git, you can:
202+
` git add .`
203+
` git commit`
204+
In your commit message, follow the guidelines from [CONTRIBUTING.md](https://github.com/angular-ui/ng-grid/blob/master/CONTRIBUTING.md):
205+
206+
- Please adhere to these [git commit message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
207+
or your code is unlikely be merged into the main project.
208+
209+
If you've made multiple commits to the code, you need to squash them into a single commit so that
210+
we don't end up with lots of small/junk commits in the overall project history. To do this you
211+
use the interactive rebase function of git:
212+
` git rebase upstream/master -i`
213+
This is basically asking git to rewrite the commit history for all commits that are different between
214+
your current branch and upstream/master.
215+
216+
Help is available from [interactive rebase](https://help.github.com/articles/interactive-rebase), but
217+
in summary when you request a rebase git will:
218+
219+
1. Display an editor with a list of commits. You effectively leave the first commit alone, and put
220+
squash in the first word of all the others. Save that, and git will attempt to squash all the commits
221+
into that first commit
222+
2. Git will then display a second editor for you to edit the commit message. This is where you want
223+
a nice clean commit message. If you're fixing an issue, then it should start with `fix #<issue number> (<functional area>)`,
224+
and then it will automatically attach to that issue and close it once merged. If you're doing documentation
225+
updates you'd often have a commit message that starts with `doco(<functional area>): <short description>
226+
227+
Push your branch up to your fork of the repository. I usually cheat and rely on git's help messages here:
228+
` git push`
229+
This will give you an error message, but also tell you what the real instruction is, which you can
230+
copy and paste:
231+
` git push --set-upstream origin 1023_nulls_to_custom_sort`
232+
233+
Now go to your homepage in git, and to your fork of the ng-grid repository. You should see a message saying
234+
that a new branch has been pushed, and asking if you want to create a pull request. Click that button,
235+
and check the list of changes again in the commit history, and that there is a good quality commit
236+
message with only a single commit.
237+
238+
Press the "create pull request" button, and wait for someone to review and approve your pull request.
239+
240+
**IMPORTANT**: By submitting a patch, you agree to allow the project owners to
241+
license your work under the the terms of the [MIT License](LICENSE.md).
242+
243+
Remember that this is a volunteer only open source project. Most of the developers are working on their
244+
own areas of the functionality, and usually doing that in stolen moments of time. They generally prefer to
245+
spend time coding their own stuff rather than reviewing the pull requests of others. Typically it'll take a
246+
couple of days for someone to find the time to review and comment on your pull request. Most people will
247+
have a few updates they're requested to make on the first couple, whilst they learn the ropes, so be prepared
248+
for that.
249+
250+

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
# Help!
88

9-
Head to http://ui-grid.info for documentation and tutorials. Join https://gitter.im/angular-ui/ng-grid to discuss development of the 3.x codebase.
9+
Head to http://ui-grid.info for documentation and tutorials. Join https://gitter.im/angular-ui/ng-grid to discuss development of the 3.x codebase. We're always looking for new contributors, for pro-level contribution guidelines look at [Contributor](CONTRIBUTING.md), if you're more of a first-timer with open source (or just need a refresher), look at [First Time Open Source Contributor](FIRST_TIMER.md), also look at [Developer](DEVELOPER.md)
1010

1111
# What Happened to Version 2.x?
1212

@@ -18,7 +18,7 @@ To submit fixes to 2.x please point your pull requests at the [2.x](https://gith
1818

1919
# How Can I Test 3.0?
2020

21-
With 3.0 we are no longer storing release files in the repository; only source files will be here. 3.0 release files are available on http://ui-grid.info, which is built from this repository: ui-grid.info/release/ui-grid-unstable.js
21+
With 3.0 we are no longer storing release files in the repository; only source files will be here. 3.0 release files are available on http://ui-grid.info, which is built from this repository: ui-grid.info/release/ui-grid-unstable.js, and the beta is available from bower as `bower install angular-ui-grid --save-dev`
2222

2323
Here is a file list for the 3.0 unstable releases:
2424

‎misc/tutorial/098_contributing_to_ui-grid.ngdoc

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
@ngdoc overview
2+
@name Tutorial: 098 Contributing to ui-grid
3+
@description
4+
5+
## Contributing ##
6+
7+
The ui-grid team is reasonably small, and this is a large project. We are always looking for
8+
contributors to assist to make this the default grid for all angularJS projects.
9+
10+
There are a number of ways you can contribute, all of which add value to the team:
11+
12+
1. Raising high quality issues in the issue tracker, and helping to diagnose and resolve them
13+
2. Assisting with documentation updates and helping others who have issues in the issue tracker
14+
3. Providing patches for point issues through submission of pull requests
15+
4. Contributing features or core development to the project
16+
17+
We are a friendly project that welcomes new members, and we have tried to provide guides that
18+
allow both open source pros and first timers to open source to contribute to the project.
19+
20+
## Issues in the issue tracker ##
21+
Refer to [CONTRIBUTING.md](https://github.com/angular-ui/ng-grid/blob/master/CONTRIBUTING.md),
22+
in the issue tracker and bug report sections.
23+
24+
In short, the issue tracker should be used for _demonstrable problems_ in the code. You should
25+
tell us what version you're using, what the problem is that you have, what you expected to happen
26+
instead, and if possible provide a plunkr that demonstrates the problem.
27+
28+
The easiest way to get a plunkr is to start with one of the tutorials, click the "edit" button,
29+
and then adjust it in the plunkr to match the configuration in your code. Then click the save
30+
button, and copy and paste the url into your issue.
31+
32+
There is a lot more detail in [CONTRIBUTING.md](https://github.com/angular-ui/ng-grid/blob/master/CONTRIBUTING.md),
33+
read it and follow it.
34+
35+
36+
## Documentation updates and helping with other people's issues ##
37+
38+
As you get more familiar with ui-grid, you'll find that some things in the documentation aren't
39+
described as well as you think they could be, or you'll start to build knowledge that is enough
40+
to answer questions.
41+
42+
Register for gitter, and get a github account. Answer questions where you have the knowledge to
43+
do so, freeing up the core team to work on the more complex issues. Remember that you don't have to
44+
always be right, this is an open source project run by volunteers. So long as you have good intentions
45+
and your courteous, then your contributions will be valued. The only way to increase your knowledge is
46+
to start, and we all started in the same place.
47+
48+
If you want to contribute documentation updates, these are the easiest area of pull requests to submit.
49+
Take a look at the [first timers guide](https://github.com/angular-ui/ng-grid/blob/master/FIRST_TIMER.md),
50+
and do your first pull request. It's not as hard as it looks from the outside!!
51+
52+
53+
## Providing patches, contributing features, core development ##
54+
55+
If you're already a pro with open source, github and the development tools, dive straight in. Look
56+
at [CONTRIBUTING.md](https://github.com/angular-ui/ng-grid/blob/master/CONTRIBUTING.md) and
57+
[DEVELOPER.md](https://github.com/angular-ui/ng-grid/blob/master/DEVELOPER.md), and get working!!
58+
59+
Key things to watch out for are:
60+
61+
1. We don't have unit tests everywhere as yet, but we want to. Pull requests should have run the
62+
unit tests before submission, and all unit tests should be working. Ask for help if you can't fix
63+
them.
64+
2. All new PRs should come with unit tests
65+
3. Similarly, we don't yet have ngdoc everywhere, but we have it in most places. All new pull requests
66+
should come with ngdocs, and where appropriate, a new or extended tutorial
67+
4. End-to-end tests are least complete, but at a minimum the existing end-to-end tests must continue to
68+
run, so run them before submitting
69+
5. Squash all your commits - each pull request should have only a single commit. It's much easier to
70+
do this before you push to github - once you've pushed to github then squashing your commits generally
71+
requires you to create a new branch.
72+
6. Follow the coding style, including 2 spaces for indent
73+
74+
If you're more of a first timer with open source, then look at [First time guide](https://github.com/angular-ui/ng-grid/blob/master/FIRST_TIMER.md).
75+
Some of it you'll already know, other bits may be new. Our aim with this guide is to collate as much as possible of the
76+
questions and answers that we've covered through gitter and other channels, and make that information
77+
accessible to new contributors.
78+
79+

0 commit comments

Comments
 (0)