mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-30 05:09:06 +02:00
Add readme to include status of docs rewrite and high level todos
Conflicts: docs/en/03_Upgrading.md docs/en/03_Upgrading/00_Upgrading.md docs/en/03_Upgrading/index.md
This commit is contained in:
Will Rossiter
Cam Findlay
parent
e9d88dd8ee
commit
79e9254f05
@ -1,41 +0,0 @@
|
||||
# Upgrading
|
||||
|
||||
Usually an update or upgrade to your SilverStripe installation just means
|
||||
overwriting files and updating your database-schema.
|
||||
|
||||
See our [upgrade notes and changelogs](/changelogs) for release-specific information.
|
||||
|
||||
## Process
|
||||
|
||||
* Check if any modules (e.g. blog or forum) in your installation are incompatible and need to be upgraded as well
|
||||
* Backup your database content
|
||||
* Backup your webroot files
|
||||
* Download the new release and uncompress it to a temporary folder
|
||||
* Leave custom folders like *mysite* or *themes* in place.
|
||||
* Identify system folders in your webroot (`cms`, `framework`, `sapphire` and any additional modules).
|
||||
* Delete existing system folders (or move them outside of your webroot)
|
||||
* Extract and replace system folders from your download (Deleting instead of "copying over" existing folders ensures that files removed from the new SilverStripe release are not persisting in your installation)
|
||||
* Visit http://localhost/dev/build/?flush=1 to rebuild the website database
|
||||
* Check if you need to adapt your code to changed PHP APIs
|
||||
* Check if you have overwritten any core templates or styles which might need an update
|
||||
* See [common-problems](common-problems) for a list of likely mistakes that could happen during an upgrade.
|
||||
|
||||
<div class="warning" markdown="1">
|
||||
Never update a website on the live server without trying it on a development copy first.
|
||||
</div>
|
||||
|
||||
|
||||
## Decision Helpers
|
||||
|
||||
How easy will it be to update my project? It's a fair question, and sometimes a difficult one to answer.
|
||||
|
||||
* "Micro" releases (x.y.z) are explicitly backwards compatible, "minor" and "major" releases can deprecate features and change APIs (see our [/misc/release-process](release process) for details)
|
||||
* If you've made custom branches of SilverStripe core, or any thirdparty module, it's going to be harder to upgrade.
|
||||
* The more custom features you have, the harder it will be to upgrade. You will have to re-test all of those features, and adapt to API changes in core.
|
||||
* Customisations of a well defined type - such as custom page types or custom blog widgets - are going to be easier to upgrade than customisations that modify deep system internals like rewriting SQL queries.
|
||||
|
||||
## Related
|
||||
|
||||
* [Release Announcements](http://groups.google.com/group/silverstripe-announce/)
|
||||
* [Blog posts about releases on silverstripe.org](http://silverstripe.org/blog/tag/release)
|
||||
* [/misc/release-process](Release Process)
|
||||
96
docs/en/README.md
Normal file
96
docs/en/README.md
Normal file
@ -0,0 +1,96 @@
|
||||
# Todo
|
||||
|
||||
This folder is a work in progress for the new SilverStripe.org documentation
|
||||
project run by Cameron Findlay and Will Rossiter. If you want to contribute
|
||||
we'd love you too so flick us a message via email or twitter.
|
||||
|
||||
The docsviewer module issue tracker has a set of functional requirements that
|
||||
we need to make as part of this work.
|
||||
|
||||
At the current point, the existing docs have just been dropped into the correct
|
||||
sections. Index files need to be written as well as perhaps files merged or
|
||||
reworked within sections.
|
||||
|
||||
## How-tos
|
||||
|
||||
How-tos should be each of the learning categories under a `howto` folder which
|
||||
is visible within the section. This separates the context of reference
|
||||
documentation to more tutorial style steps.
|
||||
|
||||
## Review *
|
||||
|
||||
Below where we say 'review' this relates to writing new index folders,
|
||||
organizing the existing pages into a cohesive structure, how-tos out to
|
||||
individual files and rewriting documentation pages in a standard and agreed upon
|
||||
language style.
|
||||
|
||||
We are also looking at using a consistent example across all the documentation
|
||||
and releasing this code on Github so that it gives developers a great reference
|
||||
of what a beautiful SilverStripe project looks like.
|
||||
|
||||
## Writing and Language notes
|
||||
|
||||
Todo
|
||||
|
||||
## Developer Guide notes
|
||||
|
||||
The developer guides are a new concept. Each guide is broken into 2 sections
|
||||
|
||||
- How tos (stored within a how-to folder)
|
||||
- Reference documentation
|
||||
|
||||
How-tos should be short, sweet and full of code. The style of these is for users
|
||||
to basically copy and paste to get a solution. An example of this would be
|
||||
`How to add a custom action to a GridField row`.
|
||||
|
||||
Everything else in the developer guide should be written as a reference manual.
|
||||
|
||||
Each section should contain an index.md file which summaries the topic, provides
|
||||
the *entry level* user an introduction guide to the feature and any background
|
||||
then it can go down into more detailed explanation into detailed references.
|
||||
|
||||
If you cannot place a how-to within a single developer guide, that would be an
|
||||
indication that it should be a tutorial rather than part of a guide. Tutorials
|
||||
should cover a full working case of a problem, the thought behind the problem
|
||||
and a annotated implementation. An example of a new tutorial would be
|
||||
'Building a Website without the CMS'. 'Building a contact form' would still sit
|
||||
under 'Forms' as while it may have templates and controllers involved, as a user
|
||||
'Form' is the action word.
|
||||
|
||||
|
||||
## Documentation Tasks
|
||||
|
||||
- [x] Create top level and second level folder structure
|
||||
- [x] Move existing documentation into the rough IA
|
||||
- [ ] Create how-to folders in each learning category to hold how tos, update
|
||||
template to show these on the sidebar
|
||||
- [ ] Update image paths
|
||||
- [ ] Set language, writing guidelines and recommendations for consistency
|
||||
- [ ] Rewrite docs homepage
|
||||
- [ ] Docviewer improvements
|
||||
- [ ] 'Review' Getting Started section *
|
||||
- [ ] Write tutorials for Building a Website Without the CMS
|
||||
- [ ] Update tutorials and docs for Building a CMS Website to use a standard
|
||||
example (to be available on Github as well)
|
||||
- [ ] 'Review' Model section
|
||||
- [ ] 'Review' Templates section
|
||||
- [ ] 'Review' Controllers section
|
||||
- [ ] 'Review' Forms section
|
||||
- [ ] 'Review' Configuration section
|
||||
- [ ] 'Review' Extending section
|
||||
- [ ] 'Review' Testing section
|
||||
- [ ] 'Review' Debugging section
|
||||
- [ ] 'Review' Performance section
|
||||
- [ ] 'Review' Security section
|
||||
- [ ] 'Review' Modules section
|
||||
- [ ] 'Review' Email section
|
||||
- [ ] 'Review' Integration & Webservices section
|
||||
- [ ] 'Review' Search section
|
||||
- [ ] 'Review' i18n section
|
||||
- [ ] 'Review' Files section
|
||||
- [ ] 'Review' Customing the Admin section
|
||||
- [ ] 'Review' Execution pipeline section
|
||||
- [ ] 'Review' CLI section
|
||||
- [ ] 'Review' Cookies and Sessions section
|
||||
- [ ] 'Review' Upgrading
|
||||
- [ ] 'Review' Contributing
|
||||
Loading…
Reference in New Issue
Block a user