{"id":16251572,"url":"https://github.com/pfalcon/change-control-manifesto","last_synced_at":"2026-01-29T14:03:49.490Z","repository":{"id":139748378,"uuid":"229616851","full_name":"pfalcon/change-control-manifesto","owner":"pfalcon","description":"Change Control Manifesto for principled Open Source projects","archived":false,"fork":false,"pushed_at":"2020-12-11T10:26:54.000Z","size":6,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-30T23:25:12.039Z","etag":null,"topics":["community","guidelines","recommendations","rules"],"latest_commit_sha":null,"homepage":"","language":null,"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/pfalcon.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-12-22T19:06:40.000Z","updated_at":"2023-09-08T18:01:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"411c8d7b-1169-4abb-aa8c-4decead4d843","html_url":"https://github.com/pfalcon/change-control-manifesto","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pfalcon/change-control-manifesto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Fchange-control-manifesto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Fchange-control-manifesto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Fchange-control-manifesto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Fchange-control-manifesto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pfalcon","download_url":"https://codeload.github.com/pfalcon/change-control-manifesto/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Fchange-control-manifesto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28879012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T10:31:27.438Z","status":"ssl_error","status_checked_at":"2026-01-29T10:31:01.017Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["community","guidelines","recommendations","rules"],"created_at":"2024-10-10T15:10:38.826Z","updated_at":"2026-01-29T14:03:49.450Z","avatar_url":"https://github.com/pfalcon.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"![XKCD 1296: Git Commit](https://imgs.xkcd.com/comics/git_commit.png)\n*(Image courtesy of [XKCD](https://xkcd.com/1296/).)*\n\n# This project maintains a Change Control Policy\n\n*(It's assumed that you came here by a link while preparing/proposing\na patch/pull request to a software project.)*\n\nShort summary:\n\n* **What**: Consistent approach to change structuring, formatting, and\n  representation.\n* **Why**: That's the only way to maintain a project over long time,\n  getting consistent (usually, excellent) results.\n* **How**: Follow the code style of the project, patch requirements, and\n  commit message style.\n* **Who**: The entire project. Maintainers uphold this policy, and all\n  contributors follow it.\n* **What's not covered**: These guidelines cover \"syntactic\" properties\n  of changes, aka how they look like. This doesn't cover \"semantic\"\n  properties of changes - what they do, whether they do it right, and\n  whether they are needed at all. These are far too dependent on a particular\n  project to be discussed in a general way (as these guidelines try to do).\n\nGeneral guidelines\n------------------\n\n### Structure of commits\n\n1. Each commit should change only one aspect of the code. Don't mix\n   changes to different components. Don't mix changes of different\n   nature, e.g. adding new functionality and code reformatting.\n2. Lean on the side of the small changes, rather than big. This is\n   especially true for people who just start contribute to a project.\n   You can easily frustrate yourself and maintainers by posting\n   \"walls of code\".\n3. Err on the side of a few smaller changes rather than one big. It's\n   trivial to \"squash\" commits together in git if needed (matter of\n   seconds). But it's order(s) of magnitude more effortful to split up\n   big, especially unrelated, changes.\n4. Sometimes, there's a conflict between adding a new feature or\n   refactoring code to make it easier/better to add this new feature.\n   As you already guessed, these are *two* independent changes.\n   Refactor the code first, then add a new feature - in 2 separate\n   commits. Or if it's not too bad, add a new feature, then refactor\n   the overall code to improve it.\n\n### Description of commits\n\n5. Each change should be well and consistently described (in the commit\n   message). That's another reason to not mix unrelated things in one\n   commit, and generally keep them small. It should be clear why the\n   change is made in the first place, and this descrption should blend\n   well with overall project change history. This is important matter,\n   and following points go into details on this.\n6. Follow the style of project's existing commit messages. Here's the\n   rule which works for any git project out there: run a `git log`\n   and write your messages in the same style.\n7. Generally, the purpose of the change should be clear just from the\n   commit title (first line of the commit message), thus titles like\n   \"fixed a small bug\" or \"added a new feature\" aren't acceptable.\n   Tell what bug is fixed and what feature is added (and yes, you\n   need to fit that within character count of a line, together with\n   p.8 too).\n8. Many projects require following format for commit title:\n   `component: Short description`. What a \"component\" is depends\n   on a project, it can be a high-level division like \"server\" or\n   \"client\", a module name, a directory name, or file name. Following\n   p.6 will give a good starting idea what should be used in a\n   particular project, and you can always ask maintainers if in doubt.\n\n### Change process\n\n8. Before even preparing to work on changes, consider whether the\n   changes you have in mind are within project's scope and will\n   benefit it. Use guidelines of a particular project to assess that.\n   It may be good idea to open a discussion ticket for changes beyond\n   trivial.\n9. Please be prepared that there is an actual review process which\n   will check adherence to these (and other, as required by a particular\n   project) guidelines.\n10. Please be prepared for iterative process, where you might be asked\n    to make various updates to your proposed patch. Note that the\n    whole idea of these guidelines is to minimize the need for such\n    changes, so more closer you follow these guidelines, the more\n    streamlined the process is.\n11. It can't be emphasized far enough the importance of avoiding big changes\n    (until you got familiar enough with the project and big refactors\n    are acknowledged by the maintainers). Start simple and small. If\n    you want a specific suggestion on how to start, find a typo in a\n    project and submit a patch for it - that should be a good litmus\n    test for the process involved.\n\nFAQ\n---\n\n* Q: But isn't only the end result matters, not the way it's achieved?\n* A: Apparently not, a result depends on many small pieces and tasks it\n  consists of. You can't really get an excellent result by doing things\n  in mediocre ways. And many software projecs are continuous processes,\n  which just deliver interim results and plan for more. Again, to\n  deliver consistent (excellent, or at least improving, defenitely not\n  deteriorating) results, there should be a process how to achieve and\n  maintain them.\n\n* Q: This all looks like some \"enterprisey\" rules. Give me a break, a lot\n  of open-source software is done in free time, as a hobby, for fun.\n* A: Good catch that these guidelines are definitely based on the industry\n  best practices. But we'd argue, that they only more important for people\n  spending their own free time on the open-source projects. It's because with\n  enterprises, somebody else sets the rules. And rules differ widely -\n  from strict to lax to non-existent. Results also differ, with bugs in\n  production, project delays, failures, etc. In all these cases your role\n  is passive, you just follow the rules (or lack of them), but the outcome\n  is not your worry. But now imagine that you want to spend some of your\n  precious, for many people literally non-existent, free time on an open\n  source project. If you do that \"for fun\", it's one matter (and maybe no\n  specific rules needed). But some people actually want to achieve some result,\n  and even more importantly - maintain the achievement over time, not let\n  it deteriorate. For them, rules similar to the outlined here are imperative,\n  or they risk to find out that they wasted a good deal of their lives for\n  nothing.\n\n* Q: Who should perform cleanups and tweaks to adhere to these guidelines?\n* A: As obvious as it may sound, you, the submitter/proposer, are the best\n  party to do that.\n\n* Q: I have better things to do than to cleanup to adhere to your guidelines.\n* A: Maintainers speaking. Same here. We maintain projects for the benefit\n  of community, and strive to provide consistently excellent results. It is\n  thus in the interest of the community to uphold the change control policy.\n  And this policy is an unalienable part of the project. Everything you love\n  about the project, it in the large part is due to this policy.\n\n* Q: What if I don't agree with this policy?\n* A: You should re-read this document again to understand why the change control\n  policy exists. If you still don't agree, that's fine - you don't have to\n  agree, you just have to follow it ;-).\n\n* Q: What if I don't follow this policy?\n* A: You will be referred to this document. And maintainers will patiently\n  wait for you to rework your changes. Overall, there will be delays with\n  processing your contribution.\n\n* Q: Why do we need \"component\" in the commit message if there's\n  `git log --name-only`?\n* A: Oh, thanks for reminding me about that obscure switch! Too bad I'll\n  forget it again soon - with hundreds of project to maintain and years\n  doing that, `git log --oneline` is the only one I learnt by heart. Hopefully,\n  that gives a good hint - we don't target git geeks here, we target general\n  public: everyone should be able to do `git log` and be able to understand\n  what/why/where/when/who. Besides, \"component\" in the commit title isn't\n  necessirily \"file\". But overall, if you don't agree, you don't have to\n  follow it for your projects, just please follow it with the projects which\n  use that convention.\n\nReferences\n----------\n\nList of documents which similarly advocate or establish a detailed and/or\nformal contribution process. (Note that the processes described at the\nlinks below may differ from the process/guidelines described in this\ndocument. They are provided as references to show that\ncontribution/commit/change guidelines are well-known and customarily used.)\n\n1. [C4 (Collective Code Construction Contract)](https://rfc.zeromq.org/spec/42/)\n2. [How to send good pull requests on GitHub (Eli Bendersky)](https://eli.thegreenplace.net/2019/how-to-send-good-pull-requests-on-github/)\n3. [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)\n4. [Keep a ChangeLog](https://github.com/olivierlacan/keep-a-changelog)\n   * This project claims: \"Using commit log diffs as changelogs is a bad\n     idea: they're full of noise. Things like merge commits, commits with\n     obscure titles, documentation changes, etc.\". They just conclude that\n     the only way around that is to keep ChangeLog. The change-control-manifesto\n     project disagrees with taking the sad situation with git logs for granted,\n     and seeks to change the root of the problem. Whether you keep an additional\n     ChangeLog beyond that is up to you.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfalcon%2Fchange-control-manifesto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpfalcon%2Fchange-control-manifesto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfalcon%2Fchange-control-manifesto/lists"}