Expand description and notes in standards README #25
Conversation
As discussed in the PR, this section felt applicable to standards generally, not just this one. Rather than muddy this PR, it has been deleted here, but added as part of a new PR (see #25)
Same as the previous change. As discussed in the PR, this suggestion would be applicable to all standards generally, not just this one. Rather than muddy this PR, it has been deleted here, but added as part of a new PR (see #25)
This is the content from the original PR for PL/SQL standards. I've had to do a certain amount of editing to the format and content of the pre-amble as part of this. The original PR also brought in the idea of all standards needing to be versioned, and these versions having to be referred to, which is something we've also extracted out as a new PR (see #25). As that has yet to be decided I've omitted that content. Also the original contribution marked the content up as headings. That's where I have re-formatted things so we have actual headings, and the extracted text then forms the section content.
|
This forms part of the refactoring of PR #8 @bensagar-ea . As this includes the idea of versioning all our standards I'm guessing there may be lots of discussion on this point alone, so shout if this needs splitting again! |
standards/README.md
Outdated
|
|
||
| ## Versioning | ||
|
|
||
| Our standards are updated on an ongoing basis. Anything using these standards should therefore refer to these standards not only be name, for example **C# coding standards**, but also by version, for example **1.0**. |
There was a problem hiding this comment.
As we are using a version control system for these standards, I don't know that we need to explicitly number them as well. I'm happy to refer to version numbers of external standards where they exist, but it doesn't seem worth the overhead internally.
I think this standard should say to refer to the date that the applicable standards were adopted, so it would be straightforward to see what versions were in effect at that point.
This stems from an agreed refactoring of PR #8 (PL/SQL coding standards). It was highlighted in that PR some of the content would be more appropriate as guidance, rather than being a standard we must all follow. So it was suggested to extract and move it into the `/guidance` section of the project. SO the content of this PR comes from @nigejohnson, structure and how the changes were made, was me @Cruikshanks I had to do a certain amount of editing to the format and content of the pre-amble as part of this. The original PR also brought in the idea of all standards needing to be versioned, and these versions having to be referred to, which is something we've also extracted out as a new PR (see #25). As that has yet to be decided I've omitted that content. Also the original contribution marked the content up as headings. That's where I have re-formatted things so we have actual headings, and the extracted text then forms the section content.
Cruikshanks
force-pushed
the
expand-standards-readme
branch
from
fef7f49 to
c7e7570
Compare
|
@bensagar-ea have updated the content based on your feedback. |
|
Couple of things: |
|
Another random thought triggered by the previous thought: a version control system is the most appropriate place to store content (especially while it is still living content that is subject to change), but is it the best place or mechanism to publish/distribute content? |
|
So after a bit more pondering on this, I think we should go with what we put in the principles:
This still seems valid to me. What's missing at the moment is a statement in the standards of when they have become effective. Can we just agree how to make that explicit? |
standards/README.md
Outdated
|
|
||
| Our standards are updated on an ongoing basis. Anything using these standards should therefore refer to these standards not only by name, for example **C# coding standards**, but also by date, for example **as at 2020-01-08**. | ||
|
|
||
| Whilst we always endeavour to keep code consistent with the latest standards, not all projects are active. This means as standards change some projects will no longer meet them. Having a reference to when the standard was last applied, will help when determining the effort to update a project |
There was a problem hiding this comment.
| Whilst we always endeavour to keep code consistent with the latest standards, not all projects are active. This means as standards change some projects will no longer meet them. Having a reference to when the standard was last applied, will help when determining the effort to update a project | |
| Whilst we always endeavour to keep code consistent with the latest standards, not all projects are active. This means as standards change some projects will no longer meet them. Having a reference to when the standard was last applied, will help when determining the effort to update a project. |
I also wonder if it would be useful to say where this reference should be? Project README?
This is the content from the original PR for Java standards. I've had to do a certain amount of editing to the format and content of the pre-amble as part of this. The original PR also brought in the idea of all standards needing to be versioned, and these versions having to be referred to, which is something we've also extracted out as a new PR (see #25). As that has yet to be decided I've omitted that content.
As discussed in the PR, this suggestion would be applicable to all standards generally, not just this one. Rather than muddy this PR, it has been deleted here, but added as part of a new PR (see #25).
As discussed in the PR, this section felt applicable to standards generally, not just this one. Rather than muddy this PR, it has been deleted here, but added as part of a new PR (see #25)
This is taken from a 'Rationale' section in the PL/SQL PR #8. We have moved it here because of the suggestion it applies to all standards.
Include in PR #8 was the recommendation that all standards should be versioned, and where they are used the version should be referred to. Again this would be some that applicable to all standards, not just PL/SQL so it has been migrated here to allow PR #8 to progress, and this suggestion be discussed in isolation. For reference, as part of the copy across I have made the following changes - slight grammatical tweaks to fit the new context - markdown formatting tweaks, namely using bold to highlight the examples - removing the line breaks within sentances. There is no need to break lines in markdown at 80 chars, particularly when it is solely for display in GitHub
As per PR feedback and discussion in the community, because the standards are version controlled we shouldn't have to manually version them as well. But if we know the date, it should be simple enough to determine the "version" of a standard being referenced.
This updates the reasoning why not all projects will meet our standards, and gives a reason why we would want a reference recorded somewhere to when a standard was last applied/checked.
Cruikshanks
force-pushed
the
expand-standards-readme
branch
from
a1e013d to
e63944a
Compare
I've put together PR #53 . Is that the kind of thing you were thinking of @bensagar-ea ? |
This stems from an agreed refactoring of PR #8 (Plsql coding standards). It was highlighted in that PR some of the content is applicable generally, not just to PL/SQL.
So it was suggested to move the more general content into the standards README.
So the content of this PR comes from @nigejohnson and questions and comments should be directed to him 😁
Anything regards structure and how the changes were made, feel free to fire at me @Cruikshanks 😰