How to port designs from v2 to v3

[BenJamesBen]

How to port designs from v2 to v3

1. Make sure you are working in the v3 branch. (On my local system in the develop branch, git fetch to get upstream branch info. git switch v3 to create and switch to the v3 branch.)
2. Create a working v3 branch. (git branch working-v3-for-porting, git switch working-v3-for-porting.)
3. Save a copy of the old config/index.js, because this file will be deleted in the next step. (In the design/[designame] folder, cp config/index.js src/config.js.old).
4. Delete the entire config subdirectory. (git rm -r config.)
5. (This has already been done for all our existing designs. You don't need to do this now. Was: For every *.js file in the src subdirectory, rename the file as *.mjs. (git mv file.js file.mjs).)
6. (This has already been done for all our existing designs. You don't need to do this now. Was: Important: commit the deleted/renamed files now. This makes sure that the history is preserved. ('git commit -m "Rename and delete files in preparation for porting [designname] to v3.`.))
7. Now, edit all the *.mjs files, starting with index.mjs. The examples below assume a design named Designname with 3 parts: base, front, and back. Examples will work on the base part.
8. In index.mjs:
   • Change import freesewing from '@freesewing/core' to import { Design } from '@freesewing/core'.
   • Add `import { data } from '../data.mjs'.
   • Delete import plugins from '@freesewing/plugin-bundle'. (But, remember that we'll need to add plugin information to one of the other .mjs files later.)
   • Delete import config from '../config'.
   • Change all the imported parts from import draftBase from './base' to import { base } from './base.mjs'.
   • Change const Designname = new freesewing.Design(config, plugins) to:

   const Designname = new Design({
     data,
     parts: [ base, front, back ]
   })
   

   Another example:

   const Benjamin = new Design({
     data,
     parts: [ bow1, bow2, bow3, ribbon ],
   })
   

   • Delete all the remaining lines in the file except for the Named exports line.
   • Change the named exports line from export { config, Designname } to export { base, front, back, Designname }. (We're exporting all parts so other patterns can inherit/use them in the future, if desired.)
     Example:

     export { bow1, bow2, bow3, ribbon, Benjamin }
     

9. In the remaining *.mjs files, at the very top of the file add any import statements that are needed.
10. Change the top export default function (part) { line to function draftDesignnamePartname (part) {. For example, function draftBenjaminRibbon (part) {. Leave all the remaining code intact.
11. At the bottom of the file after the draft function, at the minimum add code for the part:

export const partname = {
  name: 'designname.partname',
  draft: draftDesignnamePartname
}

For example:

export const ribbon = {
  name: 'benjamin.ribbon',
  draft: draftBenjaminRibbon
}

12. This format can have other optional elements, for example:

export const front = {
  name: 'brian.front',
  from: base,
  after: back,
  hide: true,
  measurements: [ ],
  optionalMeasurements: [ ],
  options: { },
  plugins: [ ],
  draft: draftBrianFront
}

13. If the part inherits (from:) or depends upon (after:) other parts, for example::
    • Add at the top import { base } from './base.mjs'.
    • Add from: base, (or after: base,, depending on the relationship)
    • If the part depends on multiple parts: after: [ base, back],
    • You will find this information in that config.js.old file you copied/saved earlier.
14. If the part needs to be hidden, add hide: true,.
15. For the first part that requires a plugin:
    • Add at the top, for example import { pluginBundle } from '@freesewing/plugin-bundle'.
    • Add plugins: [ pluginBundle ],.
    • If the part already imports a part that has already imported the plugin, don't import it a second time.
    • That means, if all the parts inherit/import from some common ancestor that imports the plugin, the plugin will be imported explicitly only 1 time total. All the remaining parts will just silently inherit the plugin.
    • That means, if the design inherits from another design's part that already imports the plugin, none of the parts in your design will need to import the plugin explicitly.
16. For conditional plugins, add for example import { withCondition as bustPlugin } from '@freesewing/plugin-bust'. Add the plugin to the plugins: [ ], array.
17. For the measurements, determine which part each measurement should go into (typically the first part that uses that measurement). Measurements can be spread out among different parts or be put into one part, depending on what makes sense for the design.

  measurements: [
    'biceps',
    'chest',
    'hpsToWaistBack',
  ],

18. For the options, determine which part each option should go into. Similar to the measurements, this will be depend on what makes sense for the design.
19. For each option, add a menu: 'menuname' section at the end to specify which menu the option should be listed under. You can use name.subname.subname2 to indicate nested submenus.

  options: {
    bicepsEase: { pct: 15, min: 0, max: 50, menu: 'fit' },
    chestEase: { pct: 15, min: -4, max: 35, menu: 'fit' },
    lengthBonus: { pct: 0, min: -4, max: 60, menu: 'style' },
    acrossBackFactor: { pct: 98, min: 93, max: 100, menu: 'advanced' },
    armholeDepthFactor: { pct: 55, min: 50, max: 70, menu: 'advanced' },
  },

[BenJamesBen]

I changed the instructions to:

• We are now leaving the existing draft function intact, changing it from a default export function to function draft (part). All the function's code is left intact and as-is.
• We are now adding the new part code below the existing draft function code.

[joostdecock]

That's great. One thing that I've changed myself is to not call the method draft because that's not very useful when debugging.
so I would call it something like wahidFront and then do:

draft: wahidFront

Now where troubleshooting an error, it's a lot easier to know it's in wahidFront than in draft which could be any part.

Not super important, just a small improvement.

[BenJamesBen]

I updated the instructions to change the draft function name to "draftDesignnamePartname", for example draftBenjaminRibbon.

[BenJamesBen]

20. For the object/elements that were pulled from part.shorthand(), instead add them directly to the draft function call, instead of the part And, include the part element at the end. Example:
    From:

function draftHiBody (part) {
  const {
    store,
    sa,
    ...
    utils,
  } = part.shorthand()

To:

function draftHiBody({
   store,
   sa,
   ...
   utils,
   part,
 }) {

[joostdecock]

Pretty sure everything is ported now. Closing.