Repo for all activity related to the ODSA Bunch of Wires Specification

We recommend that all contributors use Madoko - a live markdown editor - to write specs. There are several advantages that Madoko provides that we believe will make the contribution process easier:

• Madoko is a live markdown editor. All changes made are immediately visible on the generated document.
• Madoko has integrated their software with a number of common services - including GitHub! More on how to open documents on Madoko directly from your fork of ODSA-BoW will be provided below
• Madoko automatically enumerates sections and subsections. If you're interested in presenting your specs through other mediums (PDF, etc.) it's come enumerated
• Madoko makes it easy for users to download those documents as PDFs, HTML, and even LaTeX.

Madoko's integration with GitHub makes it really easy to open a specific file. When you open the live editor, find the folder icon on the top left corner. Choose the Open menu, and again, use GitHub.

Here, use the GitHub menu to navigate to the repo and the file that you'd like to open. Choose the file. It will open in the Madoko editor allowing you to read as you see fit! If you'd like to download the file as a PDF to read offline, Madoko provides that option.

If you'd like to contribute to ODSA-BoW and develop specifications, here's how you can.

Forking a repository will create a copy of the main repo in your GitHub account. Then, you will be able to make all the changes you need to on your local copy before re-submitting through a pull request.

Navigate to the ODSA-BoW repository. Next to the "Watch" and "Star" Buttons will be a "Fork" button. Select it

If will create a fork of the repository on your profile and navigate to the page immediately.

Keep in mind that the fork is just a snapshot of the repository at the current time. To make contribution easier, you'll need to keep your forked repo up-to-date. There are two ways to do that.

If you're comfortable with the command line, you can follow the instructions here on how to fetch the upstream and merge your fork with it.

If you'd prefer to keep your fork current via the browser, user Kirstie James has come up with a solution. You can find the instructions here

Depending on your contribution, you may be creating and adding new specs or editing and adjusting existing specs based on open issues (more an issues below).

If you're creating a new spec, you can open a new document using the Madoko live editor and start writing right away. If you're editing an existing spec, simply open the file in Madoko and start making edits.

Once you've created a new document or made edits to the existing documents, here's how you commit those changes to your forked repo.

1. Find the folder icon in the top left corner and click the "Save To" option.
2. Madoko will present a variety of options from your local drive to cloud storage options like DropBox and, very conveniently, GitHub.
3. Select GitHub. If you haven't already allowed Madoko access to your account, do so now.
4. Find the forked version of the repo, and then where in the repo you'd like to save your file.

Madoko's integration with GitHub means that when you save the file, you're actually officially committing the file to GitHub. Write a short, but descriptive commit message and save the file.

If you find the forked repository on your GitHub account, it should register the commit you just made.

Once you have committed all the changes to your fork, it's time to create a pull request. In your forked repo, you'll notice a small message that says "This branch is XX commits ahead of the master repo". In that message will be the option to create a pull request. Select it.

For the specifics on filling out a pull request, please read through GitHub's help page on creating pull requests. Link

Issues are how contributors and users of the repository can flag bugs, suggest changes to existing specs, and make requests of the repository administrators. If you're interested in Issues, you can find more on the GitHub help page describing issues. Link.

If you are raising a general issues, like a request to the administrators, you can follow the GitHub help page on raising issues. Link.

If you're reading through specifications and would like to raise an issue regarding a spec, we ask that you reference the specific line numbers regarding the issue. You can do this by opening the Raw version of the file on GitHub.

Then select the line numbers - make sure to directly click the line numbers, and not highlight the lines!

There'll be an option menu next to the selected lines (3 dots). Choose to raise an issue. That will direct start an issue. You can then proceed as normal.

If you're a contributor and you'd like to resolve an issue concerning a specific file, the process is simple. Follow the contribution guidelines above to make the edits you believe will resolve the issue, and submit a pull request. Then make sure to report the issue being resolved on the issue thread and wait for an admin to close the issue.