Updated readme documentation. Add contribution guide (contributing.md)

2016-06-07 13:52:59 -06:00 · 2016-06-07 13:52:59 -06:00 · 44b0921ba4
commit 44b0921ba4
parent 24c19b5acb
2 changed files with 64 additions and 5 deletions
--- a/contributing.md
+++ b/contributing.md
@ -0,0 +1,43 @@
+Contributing to VBA SharePoint List Library
+==========================
+
+Authoritative Repository
+------------------------
+
+VBA SharePoint List Library is hosted on gitlab.com. The authoritative repository for VBA SharePoint List Library can be found here:
+[https://gitlab.com/jaywll/VBA-SharePoint-List-Functions](https://gitlab.com/jaywll/VBA-SharePoint-List-Functions)
+
+If you wish to contribute code to VBA SharePoint List Library, you will need an account on gitlab.com. It's a free service, open to all.
+
+There's a mirror hosted on code.jnf.me that can be found here:
+[https://code.jnf.me/jaywll/VBA-SharePoint-List-Functions](https://code.jnf.me/jaywll/VBA-SharePoint-List-Functions)
+
+By all means feel free to clone or download the project from the mirror, but if you plan to contribute then gitlab.com is the only channel through which to do so.
+
+
+Contribution Process
+--------------------
+
+Once you have a gitlab.com account, here are the steps to making a contribution to VBA SharePoint List Library's codebase.
+
+### Step One: Fork and Clone Locally ###
+From the [project page on gitlab](https://gitlab.com/jaywll/VBA-SharePoint-List-Functions), click the "fork" button. This creates a copy of the repository within your own gitlab account. Next, clone your repository locally. 
+
+### Step Two: Branch ###
+Create a feature branch, check it out, and hack away!
+
+### Step Three: Commit and Push ###
+Commit the changes you've made, and push the feature branch back to origin (your copy of the repository on gitlab.com).
+
+### Step Four: Merge Request ###
+Back on your gitlab.com account, within your forked repository, select merge requests and submit a request to merge your feature branch (`username/VBA-SharePoint-List-Functions/branchname`) with the project's master branch (`jaywll/VBA-SharePoint-List-Functions/master`).
+
+Don't delete your repository yet! Keep an eye on the comments associated with your merge request. There may be further steps requested of you, such as rebasing your feature branch on `jaywll/VBA-SharePoint-List-Functions/master`.
+
+
+GitLab Flow
+-----------
+
+VBA SharePoint List Library uses a cut-down version of [gitlab flow](https://about.gitlab.com/2014/09/29/gitlab-flow/). As per the instructions above, development takes place on feature branches, and these are merged into the `master` branch when that body work represented by the feature branch is complete.
+
+Periodically, the `master` branch is merged into the `release` branch, and these merge commits are tagged with an appropriate version number. These releases occur at the discretion of the project owner: you should not request to merge a feature branch into `release`, and requests to do so will be rejected.
--- a/readme.md
+++ b/readme.md
@ -1,8 +1,24 @@
 # VBA SharePoint List Library #
+
+VBA SharePoint List Library will be a collection of VBA functions designed to allow your VBA code to interact with a SharePoint list.
+
+Currently it can create new list items, and update existing list items based on their ID. At present there is a single function: `SPListItem`
+
+## Prerequisites ##
+- Microsoft Scripting Runtime
+- Microsoft XML, v6.0
+
+In the VBA editor window choose Tools -> References.
+
+## Usage ##
+`SPListItem(SharePointUrl As String, ListName As String, ListData As Dictionary [, ItemID As Integer])`
+
+- SharePointUrl is the address of a SharePoint site (e.g. http://sharepoint/site/)
+- ListName is the name or GUID of a list on that site (e.g. MyList)
+- ListData is a VBA dictionary object containing key value pairs, where the key is the name of a field and the value is the value that will be assigned to it.
+- ItemID is the SharePoint ID of a list item that will be updated (if omitted, a new list item will be created).
+
 VBA SharePoint List Library is a collection of VBA functions designed to allow your VBA code to interact with a SharePoint list.

-Initially, it will be able to create new list items, and update existing list items based on their ID.
-
-This is currently pre-alpha code. You are welcome to use it however you wish, however future iterations published here may vary significantly from the current version, including changes to function names, input variables and return values.
-
-Community contributions are not yet being accepted.
+## Contributing ##
+Please see the contribution guide in contributing.md