It is not clear where a reader should start about devguide

[vanderaj]

That's a great idea for the main README.md. I'll put it in over the next few days.

[staylor14]

Same question. I can't make sense of the repository structure (top level branches have version numbers, and master has directories with the same version numbers) and it doesn't appear that the readme has been updated yet.

I tried to parse a couple of the issues to see if they might contain a hint, but the ones I saw just referred to topics that needed treatment. I wasn't able to find an indication of the location of the text in question.

[vanderaj]

I've asked someone to have a look at this, but because it's already there,
it seems we may have just done it wrong. If there are any GitHub gurus out
there, I would love for it to have multiple branches representing our
history. We're working on v3.0 for the record.

On Thu, Jun 5, 2014 at 10:40 AM, Steve Taylor [email protected]
wrote:

Same question. I can't make sense of the repository structure (top level
branches have version numbers, and master has directories with the same
version numbers) and it doesn't appear that the readme has been updated yet.

I tried to parse a couple of the issues to see if they might contain a
hint, but the ones I saw just referred to topics that needed treatment. I
wasn't able to find an indication of the location of the text in question.

—
Reply to this email directly or view it on GitHub
#10 (comment).

[adamvoss]

As far the history bit, I know enough Git to be able to help with making your contents match your branches. I will need a little better understanding of what you are trying to accomplish in that respect though.

Are you looking to re-write history so that it shows, for example, version 1.0 coming after 1.1?
That is history that shows something like this:

1.0 --- 1.1 --- 1.1.1 --- 2.0
                             \ --- 2010
                              \ --- 3.0

This is possible, but it would "break" things for people who have cloned the current history (all the forks for example). Because it can create difficulties for such collaborators it is generally frowned upon for commits already made public.

The other option is just making it so that when you switch branches the contents you see correspond to the version you selected (not caring what history looks like). That would be something like this:

(intermixed history) --- 1.0
                     \ --- 1.1
                      \ --- 1.1.1
                       \ --- 2.0
                        \ --- 2010
                         \ --- 3.0

[vanderaj]

I'm happy for Intermixed history, from 1.0, 1.1, 1.1.1, 2.0, 2.0.1, 2.1,
and 2010. Then I would like to just work on "trunk" (3.0) until such time
that we've finished it when we can add a proper 3.0 tagged branch (yes, I'm
a SVN refugee, no idea how git works really).

Our history was not source controlled, so I'm happy for us to break that,
but not the current contributions or forks to 3.0 (=trunk) unless we have
to do so.

This problem does not get better the longer we leave it, and with the
hack-a-thon planned, I'd really like to get it sorted and everyone happy by
the 24th of June if possible.

thanks.
Andrew

On Thu, Jun 5, 2014 at 11:44 AM, Adam Voss [email protected] wrote:

As far the history bit, I know enough Git to be able to help with making
your contents match your branches. I will need a little better
understanding of what you are trying to accomplish in that respect though.

Are you looking to re-write history so that it shows, for example, version
1.0 coming after 1.1?
That is history that shows something like this:

1.0 --- 1.1 --- 1.1.1 --- 2.0
\ --- 2010
\ --- 3.0

This is possible, but it would "break" things for people who have cloned
the current history (all the forks for example). Because it can create
difficulties for such collaborators it is generally frowned upon for
commits already made public.

The other option is just making it so that when you switch branches the
contents you see correspond to the version you selected (not caring what
history looks like). That would be something like this:

(intermixed history) --- 1.0
\ --- 1.1
\ --- 1.1.1
\ --- 2.0
\ --- 2010
\ --- 3.0

—
Reply to this email directly or view it on GitHub
#10 (comment).

[frenchi]

A quick and rough example of my interpretation of 'intermixed history' (note the branches representing each version, "origin/" naming structure preserved.) Possibly more importantly: a starting point on master that makes it easy to get involved.

I've rewritten README.md significantly, to match what I would like to see as a new contributor. Certainly open to suggestions.

https://github.com/frenchi/DevGuide

[adamvoss]

@vanderaj You can consider of master the Git equivalent of trunk. This is a relatively simple matter so resolution by the 24th shouldn't be an issue.

[adamvoss]

@frenchi Do you want to work with Andrew on getting the appropriate changes made? GitHub's Pull Request functionality will not be sufficient for getting all the needed changes done.

I am not sure I understand why you created hierarchical branches under an "origin" name. "origin" is conventionally the name of a remote.

Based on @vanderaj's input, it makes sense to [merge and] drop the 3.0 branch for the time being.

I would consider merging the not abandoned old branches into master after they are setup as desired (merge -s ours). That will show they fed into the newer contents developed in master and will keep GitHub from indicating the branches could be merged. However, since rediscovered materials are hoped to become available for old branches, maybe it would be awkward to do this.

[frenchi]

@vossad01 happy to do the leg work on this, I'm not as familiar with SVN though, so your translations may be needed. @vanderaj I've reached out on skype, I've restructured the folders quite a bit, so happy to walk through what has happened.

re: "origin" name - my mistake. I thought it had been incorrectly included in the OWASP/DevGuide repo as "origin/version", and was leaving it there to reflect current state. Agreed that it should be changed to simply the version number. I've fixed this and merge/dropped 3.0 on my fork.

Re: addition of rediscovered materials, in my view it would be easier to host them offsite, and just add a link to the wiki upon rediscovery. I suggest we archive current content, link to specific commits e.g. Version 1.1, and then go for forward-consistency. Thoughts?

[frenchi]

For a visual explanation of what was done:

https://github.com/frenchi/DevGuide/network

[vanderaj]

That's exactly right. How do I merge that?

On Thu, Jun 5, 2014 at 3:10 PM, French [email protected] wrote:

For a visual explanation of what was done:

https://github.com/frenchi/DevGuide/network

—
Reply to this email directly or view it on GitHub
#10 (comment).

[vanderaj]

And talk to me slow. I'm about as familiar with git as I am with something
I am not familiar with. (Yes, I struggled to work out what I know less than
git, and apparently, it's git).

On Thu, Jun 5, 2014 at 4:57 PM, Andrew van der Stock [email protected]
wrote:

That's exactly right. How do I merge that?

On Thu, Jun 5, 2014 at 3:10 PM, French [email protected] wrote:

For a visual explanation of what was done:

https://github.com/frenchi/DevGuide/network

—
Reply to this email directly or view it on GitHub
#10 (comment).

[frenchi]

Hah, always happy to go over things, let me know if anything is unclear. I'm also on skype, if you want to chat directly.

I'll clean it up (keep the branches, but remerge them in to one master) and send a pull request shortly, and then I'll explain next steps.

I'll use version tagging to keep things neat historically (although it may end up looking a little more like @vossad01's re-write history option).

[frenchi]

I ended up grabbing dinner, sorry that took a while.

I've created Pull Request#18 where I flattened out the history into one branch, master (branching/merging turned in to a bit of a headache). This is more in line with @vossad01's re-write history approach, but I think it's much clearer, especially considering @vanderaj said breaking backwards compatibility wasn't the end of the world. The history of commits can be seen here, and should allow us a good base for going forwards.

For clarity: this means that what was previously the DevGuide3.0 subdirectory, has now become the repository root directory. All other subdirectories have been safely stored in the history of commits (but are not present in the current version).

I've also added tags to reach version, so it will be possible to easily checkout previous versions, eg:
git checkout v1.1.1 will revert to that version.

After this pull is accepted, I can update the wiki with direct links to each commit of the older versions, and we should be able to close this issue.

[frenchi]

In terms of next steps @vanderaj, this guide outlines how to accept & merge pull requests:

https://help.github.com/articles/merging-a-pull-request

[vanderaj]

All done. Can you have a look at how that ended up?

On Thu, Jun 5, 2014 at 10:48 PM, French [email protected] wrote:

In terms of next steps @vanderaj https://github.com/vanderaj, this
guide outlines how to accept & merge pull requests:

https://help.github.com/articles/merging-a-pull-request

—
Reply to this email directly or view it on GitHub
#10 (comment).

[adamvoss]

@frenchi A GitHub pull requests cannot do all the things you describe so @vanderaj merging your request will not have the intended result.

Tags are not pushed to remotes by default (the tags you describe to not exist in your public repo); even if they were pushed they are be included in pull requests. Similarly, you cannot introduce branches with a pull request. Pull requests can only affect one branch.

Edit: Too late, it has already been merged.

[adamvoss]

Regarding closing this issue (I am the OP), all that is required for this issue is to edit the ReadMe to say something like "Version 3.0 is currently under development. Version 2.0.1 was the last released/stable version and is the recommended version for reading until 3.0 becomes more complete." Header, links, better wording all could be considered. Simply having a better branch structure does does not resolve the issue in my mind because then the question is which branch to read. Once the conversation had started here, I did not think it was worth while though to try to open a separate issue for changing the branching structure because that would split the conversation between two pages.

[frenchi]

The readme was changed to make this more clear (specifically highlighted v3.0 as dev branch, but could add something to say v2.0.1 as stable).

The branches were re-merged in to master, please look at the commit history I linked above, as I believe this has been resolved. I ended up re-writing history. Eg: v2.0.1 is available in commit: dc5a297

@vanderaj it looks good from my end.
—
Sent from Mailbox

On Thu, Jun 5, 2014 at 11:24 PM, Adam Voss [email protected]
wrote:

Regarding closing this issue (I am the OP), all that is required for this issue is to edit the ReadMe to say something like "Version 3.0 is currently under development. Version 2.0.1 was the last released/stable version and is the recommended version for reading until 3.0 becomes more complete." Header, links, better wording all could be considered. Simply having a better branch structure does does not resolve the issue in my mind because then the question is which branch to read. Once the conversation had started here, I did not think it was worth while though to try to open a separate issue for changing the branching structure because that would split the conversation between two pages.

Reply to this email directly or view it on GitHub:
#10 (comment)

[staylor14]

@adam, this became a discussion of the branching model because of the
conflation of directory structures with version numbers, and branch names
with the same version numbers. If the readme were corrected to say "Read
3.0", would that mean, "Read what's in the 3.0 directory under master," or
"Read whatever you find under the 3.0 branch"?

@french, @vanderaj, I'm not familiar with the pull request branching model.
I am, however, familiar with Git Flow (
http://nvie.com/posts/a-successful-git-branching-model/). If you're
interested in using Git Flow, let me know - I can help restructure the repo
for this model.

In any event, the restructuring work that you've done is a vast
improvement! Thanks very much!

On Thu, Jun 5, 2014 at 6:24 AM, Adam Voss [email protected] wrote:

Regarding closing this issue (I am the OP), all that is required for this
issue is to edit the ReadMe to say something like "Version 3.0 is currently
under development. Version 2.0.1 was the last released/stable version and
is the recommended version for reading until 3.0 becomes more complete."
Header, links, better wording all could be considered. Simply having a
better branch structure does does not resolve the issue in my mind because
then the question is which branch to read. Once the conversation had
started here, I did not think it was worth while though to try to open a
separate issue for changing the branching structure because that would
split the conversation between two pages.

—
Reply to this email directly or view it on GitHub
#10 (comment).

[adamvoss]

@staylor14 My remark was because there was mention of closing the issue. I understood why the discussion got off-topic which is why I did not try to move the discussion elsewhere. However, I wanted to make clear that changing the branching structure does not address the issue I reported.

Branches being more consistent with how most git scc projects are done will not tell me (or any other user) which branch to read (nor which file in said branch to read). This is the issue I raised is that OWASP sends average Web users here to get a download to read. Once here it is not at all clear what to download. Really needing to switch between branches probably makes it more difficult because there is assumption of Git or GitHub familiarity from a reader sent from the OWASP site. This would be mitigated either by a well written Read Me and/or a change to the original OWASP link to take the user to the right branch/file.

[adamvoss]

@frenchi Are you still working with Andrew to correct the remaining Git/Branching issues?

If you are not, I am still available but won't be over the weekend. When you offered after I had, you seemed eager and I don't care so much care who did it so long as it got done and Andrew is happy with the result.

[vanderaj]

Let's get it right :)

On Fri, Jun 6, 2014 at 4:10 AM, Adam Voss [email protected] wrote:

@frenchi https://github.com/frenchi Are you still working with Andrew
to correct the remaining Git/Branching issues?

—
Reply to this email directly or view it on GitHub
#10 (comment).

[frenchi]

All fair points. Separation of issues:

Original issue: Lack of clarity around where a reader should start.

@vossad01 Another pull request to further clarify where to start. @vanderaj if you're ok with changes (edit: oops, resent with correct stable number. I'm not as familiar with DevGuide history), you know what to do!

I've also updated the Wiki with direct links to the old versions, so this should also make looking up older versions easy.

I think this clarifies it sufficiently for a new contributor/reader, and is why I suggested closing. Does the readme on the project homepage make it sufficiently clear in your view @vossad01?

New issue: branching strategy

@staylor14 git-flow is definitely great, Is it overkill for what is needed? If there is more discussion around branching, maybe we can open a new issue?

[adamvoss]

Given the current state of the repository, I put forth the following recommendation regarding branches:

1. Merge branch 3.0 into master

   • There is currently a commit to the 3.0 branch that is not included in master.

2. Delete branch 3.0

   • Andrew indicated he wants to work in master and will just tag it as 3.0 on completion. This seems like a usable workflow for this project. In light of that, keeping 3.0 around in the meantime would cause confusion.

3. Fast-forward the other branches to point to the appropriate commit introduced by @frenchi

   • This will let the various versions be accessed by name rather then commit hash. I am thinking sticking with branches rather than switching to tags makes it easier for you in the case old materials resurface and you need to update one of the old versions. The branch will automatically update to point to the new changes while a tag would not.
   • This will also resolve the issue that if you select a branch on GitHub other than master you are taken back to the original multi-folder layout.

   ---

@vanderaj Andrew, there is some great documentation on Git on the Internet (the stuff on git-scm.com is good IIRC), so I won't try to do a full primer here.

At the level we are talking here the most significant difference to bring up is that Git branches are very different than SVN branches. In Git, a branch is just a pointer to a particular commit in history. When you make a commit on a branch, it updates that branch's pointer to point to the new commit. As it is just a pointer you are able to freely add and remove branches anywhere in history as well as completely change in history where they point.

The other difference that may or may not be apparent, is that with Git being distributed and branches being pointers, everyone's branches are nominally independent. Git does let define a local relationship between branches such that your local "master" branch tracks the GitHub "master" branch, that way it knows when you fetch/pull which local branch(s) should be affected. This is important because it helps in understanding why some of the changes @frenchi made in his repository are not reflected in the OWASP repository.

---

Should it be accepted, my suggestion would be accomplished with the following steps. I could do a few pieces of this will pull requests, but not all of them, so it is probably just as easy for Andrew (or someone else with Collaborator privileges) do them all.

These steps assume you have local branches following all of the remote branches (to check run git branch and assure you see branches for all the versions that exist on GitHub, if you don't let us know). While the inital steps won't fail if you don't have those branches, I think you would encounter issues when you go to push to GitHub.

Assure you do not have any uncommitted changes, then run the following commands.

git merge 3.0 master ## merges 3.0 into master
git branch -d 3.0  ## deletes 3.0
git branch -f 1.0 1d24d140de3724b6f95655e53b8d0cc6689fbfd8 ## makes branch 1.0 point to that commit
git branch -f 1.1 22228a88e380ca4b0b88cbb959b32a11174263cd ## would not need all of the digits (only need enough for it to be uniquely determined), but I was copy-pasting
git branch -f 1.1.1 71dfba584c0b11443b19a6caf47b9f1adc641679
git branch -f 2.0 382fe2bc834beaf9dd50fc195e09329be6f7116f
git branch -f 2.0.1 dc5a2977a4797d9b98486417a5527b9f15d8a251
git branch -f 2.1 cb3db9884e428575d9e0e707bed7ded7014c1d68
git branch -f 2.1.1 d542d31ca2615650225e9238de0d68f37c37a07c
git push origin --all ## push all the branches to the remote called `origin` which is by default where you cloned from.  I assume this is GitHub.
git push origin --delete 3.0 ## need to let it know you also want to delete the remote 3.0 branch

[adamvoss]

@frenchi Regarding #20, looks good. Works just fine for me. Thanks!

There is a part of me that questions whether you will encounter users really unfamiliar with Git/GitHub that will still struggle with how to acquire the files. However, if someone is concerned about that I think it should be added as another issue and be considered out of scope for this issue.

One suggestion on that other issue would be to add Releases (GitHub feature) with the word documents rendered to PDF so they could download a single file that would not have the same performance issues that the word documents may present.

[bradchesney79]

Closing this issue as the actual work to remedy the original problem is complete. Opening a new issue for concatenation and conversion to PDF. #52