-
Notifications
You must be signed in to change notification settings - Fork 383
It is not clear where a reader should start #10
Comments
That's a great idea for the main README.md. I'll put it in over the next few days. |
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. |
I've asked someone to have a look at this, but because it's already there, On Thu, Jun 5, 2014 at 10:40 AM, Steve Taylor notifications@github.com
|
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?
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:
|
I'm happy for Intermixed history, from 1.0, 1.1, 1.1.1, 2.0, 2.0.1, 2.1, Our history was not source controlled, so I'm happy for us to break that, This problem does not get better the longer we leave it, and with the thanks. On Thu, Jun 5, 2014 at 11:44 AM, Adam Voss notifications@github.com wrote:
|
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. |
@vanderaj You can consider of |
@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 |
@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? |
For a visual explanation of what was done: |
That's exactly right. How do I merge that? On Thu, Jun 5, 2014 at 3:10 PM, French notifications@github.com wrote:
|
And talk to me slow. I'm about as familiar with git as I am with something On Thu, Jun 5, 2014 at 4:57 PM, Andrew van der Stock vanderaj@owasp.org
|
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). |
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 I've also added tags to reach version, so it will be possible to easily checkout previous versions, eg: 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. |
In terms of next steps @vanderaj, this guide outlines how to accept & merge pull requests: |
All done. Can you have a look at how that ended up? On Thu, Jun 5, 2014 at 10:48 PM, French notifications@github.com wrote:
|
@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. |
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. |
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. On Thu, Jun 5, 2014 at 11:24 PM, Adam Voss notifications@github.com
|
@adam, this became a discussion of the branching model because of the @french, @vanderaj, I'm not familiar with the pull request branching model. In any event, the restructuring work that you've done is a vast On Thu, Jun 5, 2014 at 6:24 AM, Adam Voss notifications@github.com wrote:
|
@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. |
@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. |
Let's get it right :) On Fri, Jun 6, 2014 at 4:10 AM, Adam Voss notifications@github.com wrote:
|
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? |
Given the current state of the repository, I put forth the following recommendation regarding branches:
@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 Assure you do not have any uncommitted changes, then run the following commands.
|
@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. |
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 |
It is great you are working on refactoring and making the project more accessible to developers. I am new to web development and the OWASP Guide was recommended for learning security considerations. Sadly your new guide is not yet available and someone like me who needs to get started now will have to work with an older version.
The owasp.org page for the guide simply links here for download. Though, once I am here it is not easy to tell what I should be download to just read the guide.
It would be great if the main page (the root README.md) gave some direction for people wanting to know what to read. I eventually figured it out by finding the README.md files in sub-folders.
The text was updated successfully, but these errors were encountered: