{"id":18417365,"url":"https://github.com/stellar/product-conventions","last_synced_at":"2025-04-07T12:32:21.668Z","repository":{"id":46429150,"uuid":"184819510","full_name":"stellar/product-conventions","owner":"stellar","description":"A layout of all conventions to be used by all Stellar frontend products","archived":false,"fork":false,"pushed_at":"2024-07-22T05:29:46.000Z","size":345,"stargazers_count":9,"open_issues_count":5,"forks_count":6,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-03T06:40:05.406Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stellar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-03T20:58:38.000Z","updated_at":"2024-11-27T20:19:12.000Z","dependencies_parsed_at":"2024-06-18T20:04:24.781Z","dependency_job_id":"481b73d6-f3bd-44b8-95ba-804d1e102fe8","html_url":"https://github.com/stellar/product-conventions","commit_stats":{"total_commits":72,"total_committers":10,"mean_commits":7.2,"dds":0.6944444444444444,"last_synced_commit":"dfe856dc5b951304459f3399e5958a7982116bf1"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fproduct-conventions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fproduct-conventions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fproduct-conventions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fproduct-conventions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stellar","download_url":"https://codeload.github.com/stellar/product-conventions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247653211,"owners_count":20973783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T04:09:04.169Z","updated_at":"2025-04-07T12:32:16.654Z","avatar_url":"https://github.com/stellar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stellar Frontend Product Conventions\n\nThis is a repo of all conventions that the product team will use to build\nStellar's user interfaces.\n\n# Contents\n\n- [Goals](#goals)\n- [Scope](#scope)\n- [Ethos](#ethos)\n- [Tools](#tools)\n- [Process](#process)\n- [Code style](code-style)\n\n# Goals\n\n- Start with sane defaults\n- Learn once, write anywhere\n- Avoid bikeshedding\n- Spend less time and energy bootstrapping projects\n- Have an upgrade path for legacy projects\n\n# Scope\n\nAll frontend products created from now (May 3, 2019) should follow these\nconventions, unless there's a good reason not to. Every exception makes the\nrules harder to follow, so please avoid making them.\n\n# Ethos\n\n## Above all, write code for others to read\n\n- Prefer straightforward code that explains itself over clever code.\n- Be deliberate about variable, function, and component names.\n- Pick straightforward inputs and outputs for functions and components. They\n  should line up with the name.\n- If something will be used more than once, write unit tests and/or a story.\n\n## Don't ask for permission\n\n- Mistakes are okay. Iterating is good.\n- State your plans out loud.\n- For anything longer than a couple sentences, write a spec.\n- You don't need permission to merge, you have the privilege and responsibility\n  to merge.\n\n## Use the tools as much as possible\n\n- Prefer declarative over imperative.\n- Use React lifecycle methods sparingly, but prefer it over doing things outside\n  of React.\n- Don't be afraid to use Redux, especially if have a lot of pass-through params.\n- Try really, really, really hard to use an existing helper func, constant,\n  basic, component, or feature.\n  - Consider refactoring or abstracting (and adding any needed tests or other\n    supporting code) if there's something close, but not quite what you need\n\n# Process\n\nThis is intended as a baseline, a starting point that projects will evolve to\nsuit their needs\n\n- Pick the top card off the sprint backlog that you can do that's not assigned\n- Using checklists/subtasks, break the task down into half-day chunks\n- Ideally, after each chunk, the site will build and work; but don't agonize\n  over this\n- For each chunk:\n  - make a shared branch named `\u003cinitials\u003e-taskname`, i.e. `mz-marketsrewrite`\n  - Do the thing\n  - If you start doing the thing and find unexpected complexity:\n    - Step back and come up with a plan\n    - Post your plan in the most relevant slack channel\n  - Make a PR for your change and post a link in `#product-frontend`\n    - See [writing a PR](#writing-a-pr)\n  - Address any feedback\n  - Merge it into master once all checks pass, and you're comfortable with it\n\n## Writing a task\n\nWhether an Asana task, GitHub issue, Trello card, or something else, a task\nshould have enough information that anyone reading it can understand what needs\nto happen. Spend a little extra time on them to add information. It won't be\nperfect, it should have information that anyone coming across it blind can\ngather more details on their own, without having to ask what a ticket is about.\n\n## Writing a PR\n\nReviewing code without context is difficult, so add as much context as you can\nwithout it being a burden, but avoid referencing private materials in\nopen-source PRs. Summarize the problem, describe the intent of the solution, and\npoint out any particularly interesting parts of the code. Try adding screenshots\n(even annotated!) or screen recordings if the issue is difficult to communicate\nwith words.\n\nPR titles are used as commit mesages, so make them concise and descriptive.\nThey're trimmed to 70 characters when displayed in GitHub.\n\n# Code style\n\nRead [our styleguide](./STYLEGUIDE.md) for more information.\n\n# Plans\n\nA plan is (1) a problem you're facing with (2) one or more approaches that solve\nthat problem. Thinking through and announcing your plan out loud is a better way\nof solving problems than diving in immediately:\n\n- You approach a problem _with intention_ instead of _blindly_\n- Posting your plan in a Slack channel informs others what you're doing and how\n  you're doing it\n- People have the opportunity to correct misconceptions, suggest alternatives,\n  or otherwise improve your plan before you've spent time implementing them\n\nThe effort to make a plan should be proportional to the effort to execute the\nplan.\n\n- If it takes longer to write a plan than execute it, Just Do It\n- If the project takes an hour or less, write a sentence or two\n- If the project is a couple days or more, consider writing it in a markdown\n  file\n\nMake sure you think hard about what your \\_actual problem is. Let's say your\ntask is to \"build a function that takes a number and outputs that number's\nLebowski coefficient.\" So you write a plan:\n\n```\nI'm working on the Lebowski coefficient, and my plan is to figure out what a\nLebowski coefficient is.\n```\n\nThat's not a very specific plan: it doesn't give you actionable steps to take,\nand it's not substantive enough for someone else to comment on.\n\nOne of the reasons is because it misattributes the problem at hand. It's not\nthat you find Lebowski coefficient; the problem is _you don't know what a\nLebowski coefficient is._\n\nThis is a much better plan:\n\n```\nI'm working on the Lebowski coefficient and I don't know what a\nLebowski coefficient is, so I'm going to Google around for definitions.\n```\n\nThat's a concrete plan! And maybe it's one for someone else to point out an NPM\nrepo that calculates them automatically, or that a blog has covered the topic\nsuccinctly, or that our project cut Lebowski coefficients last week.\n\nPlans about exploratory problems are some of the most useful to think out loud\nabout, because they have more ways to attack them, which generates better\ndiscussion than problems with obvious solutions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstellar%2Fproduct-conventions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstellar%2Fproduct-conventions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstellar%2Fproduct-conventions/lists"}