Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

107 living documentation refactored #149

Merged
merged 3 commits into from
Jul 3, 2018
Merged

107 living documentation refactored #149

merged 3 commits into from
Jul 3, 2018

Conversation

o-orand
Copy link
Member

@o-orand o-orand commented Jun 18, 2018

No description provided.

@o-orand o-orand force-pushed the 107_living_documentation_refactored branch from c744a42 to 60e1eb4 Compare June 20, 2018 14:45
gberche-orange
gberche-orange requested changes Jun 27, 2018
View reviewed changes
Copy link
Member

@gberche-orange gberche-orange left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please consider updating README.md w.r.t. to stemcell management that were updated in release 20 as part of #129:

  • deployment-dependencies.yml still mentions stemcell as well as the FAQ section
  • Add a dedicated "bosh stemcell manegement" that describes the current

Besides, on the reference data set

  • add comments to the shared_condfig.yml # provides a default value for stemcell to use. Can be overriden in private-config.yml in config repo

Please also update #129 with actual specifications implemented, and add a new issue for next features to be implemented

@o-orand o-orand force-pushed the 107_living_documentation_refactored branch from a0ccfe6 to 0488cd4 Compare June 28, 2018 09:07
@o-orand o-orand force-pushed the 107_living_documentation_refactored branch from 72d8774 to 9670fc4 Compare June 29, 2018 15:43
lucaspinto
lucaspinto suggested changes Jul 2, 2018
View reviewed changes
Copy link
Contributor

@lucaspinto lucaspinto left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There're two things I'd rework:

  • I'd follow some of the Rubocop advices
  • I'd rename are_ok? to something like are_present?

@o-orand
Copy link
Member Author

o-orand commented Jul 2, 2018

@gberche-orange , @lucaspinto changed done

@o-orand o-orand force-pushed the 107_living_documentation_refactored branch from ecd9a45 to 0ff2d7d Compare July 2, 2018 15:06
gberche-orange
gberche-orange requested changes Jul 3, 2018
View reviewed changes
Copy link
Member

@gberche-orange gberche-orange left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @o-orand please see refined stemcell documentation wording suggestion.

Additionally https://github.com/orange-cloudfoundry/cf-ops-automation/blob/107_living_documentation_refactored/docs/reference_dataset/config_repository/private-config.yml should probably include fully supported properties (ideally uncommented to be covered by automated tests)

Readme.md Outdated
The same stemcell is used for all deployments, it is defined in [shared-config.yml](docs/reference_dataset/template_repository/shared-config.yml)
or in [private-config.yml](docs/reference_dataset/config_repository/private-config.yml), but the version is managed by
`root-deployment` using dedicated [<root-deployment>-versions.yml](docs/reference_dataset/template_repository/hello-world-root-depls/hello-world-root-depls-versions.yml)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@o-orand thanks for the documentation update.

Suggestion improvement below:

In order to be portable across multiple infrastructures, and allow for centralized stemcell upgrades, deployment authors rely on COA to manage stemcells including offline replication, uploading to bosh director and purge, and stemcell version selection at deployment time. Deployment authors therefore use the following syntax in their deployment manifests:

stemcells:
- alias: trusty
  os: ubuntu-trusty
  version: latest

At deployment time, the deployment manifest is transformed by COA to load the expected stemcell version (say 3586.25).

The same stemcell generation (currrently ubuntu-trusty) is used for all deployments as defined by authors in shared-config.yml
or overloaded by operators in private-config.yml.

The exact stemcell version (say 3586.25) is used within a root-deployment as defined by authors in <root-deployment>-versions.yml

Ability to support more than one stemcell (e.g. both trusty and `xenial) is considered in #155
Ability to fetch conditionally fetch online stemcells is considered in #128
Ability to for authors to use different stemcell version per deployment is considered in #15

Copy link
Member

@gberche-orange gberche-orange Jul 3, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additionally the stemcell sections would better live in the Template engine reference documentation section than in the FAQ

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the rewording, I will update the readme accordingly except the last part with issue reference. I'm not sure we need to reference issue in the readme.
About private-config.yml, the overriding mechanism is already Unit Tested in config-spec.rb , I won't include more tests in reference_dataset to avoid a reverse test pyramid (ie more acceptance test than unit test).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gberche-orange as discussed I've included commented values for private-config.yml

@o-orand o-orand force-pushed the 107_living_documentation_refactored branch 2 times, most recently from 10261e5 to 317b9de Compare July 3, 2018 14:42
gberche-orange
gberche-orange approved these changes Jul 3, 2018
View reviewed changes
Copy link
Member

@gberche-orange gberche-orange left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks @o-orand !

@o-orand o-orand changed the title WIP-refactor to be squashed into previous commit 107 living documentation refactored Jul 3, 2018
@o-orand o-orand mentioned this pull request Jul 3, 2018
Closed
@lucaspinto @o-orand
docs(living_documentation) rework
81c9584 
TODO:
 - add feature descriptions to illustrate bosh / TF / cf-apps/ concourse-pipeline pipelines
 - ensure all tests from spec/reference_dataset/reference_dataset_spec.rb are covered by cucumber feature, and then delete spec/reference_dataset/reference_dataset_spec.rb => credentials management is missing !

Done:
 - gem update
 - rework sample tf files
 - Lucas review
 - fix reference_dataset_documentation lib tests (Pipelines handles an output dir,...)
 - remove 'should' from feature
 - cucumber generated pipelines are in docs/reference_dataset/pipelines
 - add 'docs/reference_dataset/pipelines' cleanup, before running tests
 - updated reference_dataset_documentation lib to handle config dir without a root_deployment
 - cleanup gitignore
 - update readme
@o-orand o-orand force-pushed the 107_living_documentation_refactored branch from 317b9de to 81c9584 Compare July 3, 2018 15:52
@o-orand o-orand merged commit c7968fd into develop Jul 3, 2018
@o-orand o-orand mentioned this pull request Jul 11, 2018
Closed
@o-orand o-orand deleted the 107_living_documentation_refactored branch July 12, 2018 14:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@lucaspinto lucaspinto lucaspinto approved these changes

@gberche-orange gberche-orange gberche-orange approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@o-orand @lucaspinto @gberche-orange